API Architecture Strategy As soon as we start working on an API, architecture issues arise. Many mistaken API Big picture common beliefs turn out to be fiction in this area. A poorly designed API architecture SOA (Service Oriented Architecture) fulfilled the promise of breaking will lead to misuse or – even worse – not be used at all by its intended clients: down the monoliths but its implementation came with many pitfalls. application developers. Architecture: WOA (Web Oriented Architecture) is a subset of SOA based on RESTful To facilitate and accelerate design and development of your APIs, we share our vision and beliefs with you in this Reference Card. They come from our direct experience on API projects. From SOA to WOA. microservices and tends to correct mistakes from past implementations. API Levels The API level you are targeting can be reflected by the type of consumers you are *SOA shouldn’t be confused with its past implementations. From addressing. SOA* 2000, the implementation is WS-*/SOAP at 99.% WOA Level 2 « Partner API » Level 3 « Open API » Level 1 « Internal API» API used by internal developers API used by internal developers, partner API used by the company ARCHITECTURE Service oriented by design: ARCHITECTURE Resource-oriented by design: ensures a unique representation of each & partner developers developers & external developers multiple services can be provided, resource, regardless of the number of consumers. results in a huge number of services with slight variations depending on consumer needs. The main difference lies in the way you need to “industrialize” the enrolment process Explicitly assumes the nature of the WWW network: strengths and weaknesses. and the quality required for your API. At Level 1, if an application developer faces an issue, he can directly meet the guys from the API team RPC approach: abstract of the distributed nature of the WWW network. MAJOR Simple and based on common Web standards (HTTP, URI, DNS…) used since You should target Open API from the beginning (even if you are targeting Level 1 or IMPLEMENTATIONS the 90s. 2 in the short term): MAJOR Heavyweight specific protocols (WS*). & PROTOCOLS So that you can fully industrialize the way developers consume your “services” on your developer IMPLEMENTATIONS Use HTTP as the “universal” applicative protocol. No need to reinvent the portal: https://developers.fakecompany.com/ & PROTOCOLS wheel so that developers can quickly use APIs, which offer good affordance. Use custom applicative protocols on top of HTTP and SOAP, that developers This is the only way to offer good enrolment, TTFAC* & support in a digital way have to learn before calling any service. Security is based on simple Web protocols, device-agnostic by design: Security is based on a VPN or/and complex WS standard designed for server OAuth2 and OpenID Connect. to server exchanges. INTEGRATION Suits both a façade pattern and a microservices pattern (the last one being the Which API Strategy? PATTERNS true distributed nature of the Web). INTEGRATION Often implemented through a façade pattern which consists of a monolithic bloc. PATTERNS In a microservices implementation, each API team is fully responsible for their Often concentrates complexity in the hands of a centralized ESB tool/team product: each team is responsible for the quality (SLA) of their resources Integrating your legacy SOA Focusing on the REST approach inspired which has no ownership of business referentials. instead of putting it into an ESB. implementations into your API by Web Giants… may end up building a Often thinking by vendor & tools first: ESB, BPM, BAM... Think API First. Strategy… could end up with an state of the Art API URBANIZATION Strategy RESTful, Developer portal, TTFAC* & DX**, Monitoring, Accounting. X-device / X-channel. WWW.OCTO.COM CONSUMERS Clients are mostly servers. CONSUMERS X-devices: clients are servers, native mobile apps, browsers… * “Time To First API Call” is the time a developer needs to consume the API in production after reading the documentation on the developer portal! We target 5 minutes. ** “Developer experience”. APIs are used by humans. We target a massive adoption, so we should craft them with love. SERVICE ORIENTED ARCHITECTURE WEB ORIENTED ARCHITECTURE SOA WOA (REST API based & � services based) Why an API Partner Partner App #1 App A A’ #2 Partner App #1 App #2 App API #3 We believe that ATAWAD strategy? - Web single Page Applications - Native Applications IS THE ENGINE OF SOAP SOAP HTTP HTML HTTP Json over - ... Service A Service A’ request CSS request HTTP JS REST REST REST REST Offer a consistent customer Images journey “Anytime, Anywhere, Any device” are the key problems DIGI+AL STRATEGY HTTP HTTP status request (+JSON of digitalisation. API is the answer to “Business WE KNOW that the Web infiltrates +HATEOAS) Agility” as it allows you to rapidly build new GUI for APP. APP. REST API Multiple servers https://api.fakecompany.com/v1/{resouces} - Centralized Business Logic upcoming devices. AND SERVER SERVER (one for each transforms COMPANIES accessible over the network application) - HTTP as the universal MVC API Gateway applicative protocol An API layer enables Embrace WOA WE WORK OGETHER, REST proxy API Gateway + - One single API entry-point Cross device “Web Oriented Architecture” Business Delegate - Monitoring, Throtting with passion, TO CONNECT - 360° Customer View Cross channel Build a fast, scalable & secure 2017 - All rights reserved © OCTO Technology 360° customer view REST API SOAP SOAP Based on: REST, HATEOAS, Services Services Stateless decoupled BUSINESS & IT Open API allows APP. SERVER APP. SERVER APP. SERVER APP. SERVER � SERVICES µ-services, Asynchronous Independent resources To outsource innovation patterns, OAuth2 and OpenID APP. SERVER REST API REST API REST API REST API Agnostic of consumers We help you CREATE Potentially provided by To create new business Connect protocols /customers /products /stocks /payments different teams and Centralized Business /prospects /carts models Leverage the power of your SOA Business Layer technologies OPPORTUNITIES AND EMBRACE Logic accessible over existing Web infrastructure the network - GET /products - PATCH /carts/{product:1} - Often implemented - PATCH /stocks with SOAP Inside & Out - POST /payments THE WEB - Potentially can end up - PATCH /orders DISCLAMER with a huge number of - ... services with slight This Reference Card does not claim to be 100% accurate. The design variations depending concepts shown here are a result of our previous work in the REST DATA DATA DATA DATA on consumer needs. area. Please check out our blog http://blog.octo.com, and feel free DATA getProductsA() to comment or challenge this API cookbook. We’re really looking getProductsA’() Database Database Database Database forward to talking with you. Database addProductToCart(1) updateStock() validCustomerPayment() [email protected] completeOrder() FAKECOMPANY ... FAKECOMPANY WWW.OCTO.COM SOAP API architecture API vs REST stakes security NON- INTERVIEW STATELESS ASYNCHRONOUS TRANSACTIONAL HTTPS SOAP You should build stateless resource providers. A request should always offer low latency. An With REST, you’ll have to drop transactions (from Please note that ACID transactions are absolutely All requests (OAuth2, IDP, API) must be secured Nick Gall A stateless API provider is easier to distribute, acceptable response time could be 200ms. a client point of view). HTTP is not transactional. not mandatory. A good illustration to keep in with TLS (RFC5246). Portfolio Design Lead at IBM / VP Gartner at Group mind is that “Starbucks is not transactional!”: AUTHENTICATION scale and cache. TLS provides confidentiality via encryption. 1. On a functional level: You may manage transactions with one the “WS-* style Web Services are «Web» in Stateless doesn’t mean that there is no state. following solutions: You order, then you pay, then you get your drink. TLS provides data integrity via keyed MAC name only… The W3C should extricate itself There are actually two kinds of state: You should switch to an asynchronous flow if If something goes wrong between the two OpenID Connect protocol could be used to by checking (SHA-256). from further direct work on SOAP, WDSL, or Client handles application/session state: where response times exceed the limit you consider 1. Use compensating actions operations (which probably happens in 0.01% of authenticate both client (application) and user you are in the interaction, navigation, session. acceptable. This limit could be 1s. Technically, resource state, or request response, and all purchases) you’ll deal with a compensating on private API resources. any other WS-* specifications” implementing rollback logic inside API consumer. Server handles only resource state and no the resource provider queues the request and action. Once in place, OpenID Connect allows you: 2007 - https://www.w3.org/2007/01/wos-papers/gall sends 202 response to the client. session. Each request is self-contained. For example, to book an hotel room and a plane to manage your own OAuth2 instance to ticket on two different providers: You should not design an architecture based on SOAP VS REST: PATCH /orders/007 -d ‘{“status”=“complete”}’ exceptional behaviors. authorize access to API resources, David Orchard IT’S ABOUT < 202 Accepted AUTHORIZATION to use your own OpenID Connect provider to Principal Engineer at @WalmartLabs / WS standards at BEA ARCHITECTURE When the request is processed, the user is informed authenticate users,