API Architecture Strategy As Soon As We Start Working on an API, Architecture Issues Arise

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 We believe that API #3 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 API Gateway applicative protocol MVC 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 /prospects /carts different teams and models SOA Business Layer Centralized Business technologies Leverage the power of your 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, “Given the complexity of just SOAP and by another channel: HTTP2 server push, websocket, POST https://api.hotel.com/orders API_KEY should be used to authorize client to use any external OpenID Connect provider WSDL, how many developers will really be RPC & SOAP email, sms, or polling. < 201 Created to authenticate users: Google, Facebook and MICROSERVICES < Location: https://api.hotel.com/orders/768 WAF (application) on public resources able to move to the full stack?... The promise Are operation/service oriented POST https://api.travel.com/orders so on… Asynchronous processing may have heavy impacts OAuth2 (RFC6749) should be used to authorize of WSDL 2.0 has not materialized and is Tend to unify local and remote computation on business workflows. < 500 Are contract & server oriented DELETE https://api.hotel.com/orders/768 INFRASTRUCTURE both client (application) and users on private API Web Giants will probably handle authentication unlikely to do so” Microservices is a key feature of Web Oriented resources. better than you ever can: two-factor authentication 2007 - https://www.w3.org/2007/01/wos-papers/bea Architectures. At some point, you may consi- 2. On a technical level: REST An asynchronous batch could have also triggered OAuth 1.0 (RFC5849) is now obsolete as OAuth2 with sms… Is resource oriented der splitting your CORE IT systems into de- You may consider Cloud hosting over Requests sent by the client should always be an email to the user: “Sorry, your order could brought two major improvements: Explicitly uses WEB distributed architecture coupled medium-grained microservices. asynchronous (XHR for browser’s app). OnPremise hosting, as API should be as close Steve Loughran Is developer oriented not be completed…” and revert to previous Digital signature of requests were replaced by TLS. Medium grained microservices would be: each as possible to users’ devices to provide an Apache Axis committer The resource provider may be asynchronous (see successful operations. OAuth2 supports any kind of device (native, resource provider is responsible for a set of re- optimum response time: “The only place SOAP survives is in the Simplicity wins again non-blocking/reactive architectures). You will get web browser, servers…). sources that are functionally related a system that is concurrent by design. 2. Adopt an explicit resource design which The “OAuth2 dance” to authenticate and COMMON enterprise because if you can control both Fine grained microservices would be: each re- reveals the underlying transaction. authorize users involves several HTTP calls. Keep in mind that OAuth2 is mandatory to PITFALLS ends of the conversation, you can use the SOAP is Not Dead - source provider is responsible for one resource For example, to make a money transfer between Safe method calls should be cached with protect private resources (e.g. when the end user same toolkit and eliminate interop” It’s a Zombie in the Enterprise. resource A and B, instead of calling: standard Web tools. needs to be authenticated with a login screen): 2007 - http://www.1060.org/blogxter/ Business & technological stakes are: If you are targeting “Digital”, you should not Your API should be REST based A WAF RP should not be used. The following consider any other protocol: OAuth1, SAML2, Short TTM & adaptability issues should be addressed by your API platform: etc. “OpenID Connect was designed to also PATCH /accounts/a {amount : balance-XX} /customers/007?client_id=API_KEY –H Antoine Chantalou Keep complexity under control DOS/DDOS protection is generally offered by support native apps and mobile applications, Head of WOA & API at OCTO Technology PATCH /accounts/b {amount : balance+XX} ‘“Authorization”:”Bearer X.Y.Z”’ 6% • Small and manageable resource providers whereas SAML was designed only for Web- 13% REST cloud IaaS, PaaS platforms. /customers/007/accounts?client_id=API_KEY –H “By choosing REST and Web Oriented • • Limited component lifecycle synchronization based applications”. •SOAP Authentication, Authorization, Accounting is ‘“Authorization”:”Bearer X.Y.Z”’ 10% Technology leveraging You could design a «transfer» resource that Do not use encryption/signatures on the Architecture, you’re putting all the chances •Other provided by OAuth2/OIDC. 2006 58% 2016 • Scalability & performance would allow: applicative side. on your side to succeed in your API OAuth2 is not mandatory for public resources. 29% 84% • Appropriate technology for the right usage Confidentiality, Integrity is provided by TLS. strategy… SOAP is an amazing example Client Credentials flow can be used if you wish to Do not implement custom security solutions. of how businesses can embrace complex Note: if you decide to implement microservices, An RP that forbids any HTTP methods (PUT, protect all your endpoints with OAuth2. But an A handy way of avoiding implementing your POST /transfers {acc1 : a, acc2 : b, amount : XX} PATCH, DELETE…) is incompatible with an API API_KEY is sufficient for public resources: architectures and solutions” Distribution of API protocols and styles, based on directory of APIs listed at then this requires a compatible organization and own OAuth2 provider is to use an out-of-the- 2015 - APIdays conference in Paris ProgrammableWeb, May 2016. culture (small short-cycle teams and Devops). strategy. /products?client_id=API_KEY box implementation.

API team API SQUAD API management API integration API Management solutions generally Common pitfalls offer the four following features: organization 1. An API Management tool is not a Golden patterns Hammer. 1 API MANAGEMENT PORTAL TO CREATE YOUR API, THERE ARE TWO INTEGRATION PATTERNS TO CONSIDER: Your API strategy will impact your teams and organization . API Strategies are often summarised as “buying Users enrolment the right API Management product”. This Publication / versioning 1. Façade pattern As Conway’s Law says: “Any organization that designs a system [...] will inevitably produce a design Usage statistics reference card enumerates several aspects that whose structure is a copy of the organization’s communication structure”. Quotas should be addressed in an API strategy. These The “façade” pattern is used to provide a simplified interface (API) to hide the complexity of your BUSINESS ANALYSTS [Business] PRODUCT OWNER [Business] aspects concern three levels (functional, system. This pattern can actually be implemented in two ways: You should organize your teams as you would like your IT system to be. Co-design API resources Sync development with other teams technical, organizational). with a product ( ) with custom development ( ) Write automated functional Responsible for API success 2. DEVELOPER PORTAL Buy or Build You should consider a small autonomous and empowered agile team to build your API. Let’s call it tests (TDR) Define Follow-up indicators Self-enrolment API Management products address at most 20% the API squad. API Doc / Try-it interface of API Strategies stakes. 2. Microservices pattern (a key feature of Web-Oriented-Architecture)

3. SECURITY 2. Implementing an API façade with an API API_KEY façade solution (ESB) as a target architecture. PRE-BUILT FAÇADE PATTERN CUSTOM FAÇADE PATTERN MICROSERVICES PATTERN OAuth2 / OIDC complicated stage stage Editors often focus on the façade feature (e.g. Use an API Management (actually an Develop a custom App (Proxy) that will This pattern consists to rebuild pro- SCALING API 4 ESB, Gateway), but they should focus on ESB) to expose a REST API based on provide a REST API based on existing gressively your existing referentials to API MVP . API FAÇADE Managing your API. Your API should be built existing services. services. expose a pure RESTful API, directly (ESB) use with caution with specific developments. from your CORE IT systems.

Short time to market Short time to market (good for a MVP). Not dependent on an editor. When you are building your API, you generally When the MVP is validated, you should switch + + + (good for a MVP) Not dependent on an editor. Will handle the complexity of your create an API squad to set up some CORE to a microservices pattern (see “API integration + + + Will handle the complexity of your business logic. functionalities that need to be centralized: patterns”). business logic. + No performance overhead. API Management portal. In order to scale, the first API team remains and Developer portal. continues to be responsible for the global API: DEVELOPERS [IT] TECH-LEAD [IT] - Dependent on the API Management/ - A performance overhead should be - Not time to market for your API MVP. ESB editor. considered. OAuth2 or OpenID Connect. The Product Owner ensures that the API is Design & develop API resources Design & develop API resources Write API documentation Write API documentation - May not handle the complexity of your - The façade and your existing services consistent. business logic. This team could set up the first set of API Measure and improve API performance Measure and improve API performance become highly coupled. BUILD - A performance overhead should be resources to validate the API MVP, with a façade The role of the Community Manager increases. Write unit automated test Write unit automated test Build BUILD Strategic assets considered. Unique, pattern, and that’s OK. Other resource provider teams have to be set up and fast innovation - The API Management/ESB and your differentiating existing service become highly coupled. The API squad should include all members that as needed using the same model. The API team Perceived as a “delegates” and coaches resource provider vs Buy are responsible for it, typically: competitive squads (REST, API design…). Each CORE IT A Product Owner from Business or Marketing. You should distinguish between building advantage WHICH PATTERN SHOULD I USE? component publishes REST resources that it your API from managing your API. Developers (optionally a Technical Leader). is accountable for. API façade is progressively In most cases, a “façade pattern” is actually an anti-pattern, that OPS. decommissioned. API - BUILD BUY! was widely used to implement SOA with ESB. to all Cheaper When it make sense, a Community Manager. The API becomes the main entry point Common resources companies in You should consider façade pattern as a transitional solution, never to your CORE IT the sector as a final one. The façade constrains are: The total team members should not exceed 10. Perceived as a production asset API SQUAD Critical & differentiating components The resulting API will be limited by your underlying back-end STAGE TWO A Key to a competitive advantage services: ”A great API on bad services is lipstick on a pig”! A bottleneck API team not adapted to “scale API”. COMMUNITY MANAGER [Marketing] ESB are ineffective to build good API The team will not handle the complexity of CORE IT business logic. Drive External Developers (API users) OPS [IT] BUY Social networking Automated testing PORTALS & SECURITY - BUY BPO* The façade will be tightly coupled to existing back-ends. API SQUAD RESSOURCE RESSOURCE RESSOURCE API Evangelist Ex: if a CORE system evolves, the façade is impacted. PROVIDER PROVIDER PROVIDER Automated deployment API Management portal Common to all companies STAGE ONE Administrate developer portal SQUAD SQUAD SQUAD Scalability (elasticity) and SLA Developer portal Perceived as a resource With time, the API façade will become a huge monolith hard to Security *Business Process Outsourcing maintain. Response time overhead.