Asynchronous APIs: robust APIs in the post-REST world

REST, the king for inter-service APIS is not longer enough. In this talk I go over the design limitations of RESTful APIS and the alternatives to build production-ready APIS.
Presented at APIDAY MADRID 2017

Transcript

1. Asynchronous APIs Robust APIs for the post-REST world @garcianavalon
2. My evolution designing APIs A new architecture style Tooling for this new style
3. All begins with a very simple service... Teams and users Billing Stripe MongoDB Teams and users Billing MQ WebApp Admin Portal Other services Other services
4. Are we using the right tool?
5. But REST is cool! Isn’t? • REST -> representational state transfer, technique for interoperability ◦ Client-server ◦ Cacheability ◦ Stateless ◦ Hypermedia as the engine of application state (HATEOAS) • RESTful -> Architecture style virtually always on top of HTTP protocol ◦ Use HTTP verbs (request methods) to provide meaning to the request itself ◦ Use HTTP response codes to provide meaning to the response itself
6. The problems with RESTful APIs
7. The problems with RESTful APIs - semantics • There is no “official” standard. REST is an architecture style, not a protocol • Little agreement on what HTTP error codes really mean • The REST vocabulary is not fully supported everywhere • The REST vocabulary is not rich enough for APIs • HTTP is NOT extensible!
8. Guess the REST! If there are no posts, what should be the answer to GET /posts/list ? A) 404 Not found B) 204 No content C) 200 OK + JSON body with empty list
9. Guess the REST! If there is no post with id=1, what should DELETE /posts/1 return? A) 200 OK B) 404 Not found C) 304 Not modified D) 417 Expectation failed
10. The problems with RESTful APIs - complexity • Our backend code is not resource oriented • HTTP is hard ◦ GET and POST only syndrome ◦ 200 OK only syndrome • Request/Response information in many places • RESTful APIs are hard to debug
11. Guess the REST! GET /posts/12 returned 404 Not found. What happened? A) A post with id=12 is not present on the server B) The endpoint /posts doesn’t exist in the server
12. The problems with RESTful APIs - architecture • RESTful APIs coupled to HTTP ◦ But we are sending JSON payloads... • Only one type of communication: client-server request-response ◦ No publish/subscribe, notification, etc. • HATEOAS constraint is hard to implement ◦ But provides little benefits!
13. REST is not the BEST
14. RESTful APIs are not a good choice for • Realtime • Efficient querying • Microservices • Asynchronous communication • One-to-many communication HTTP Limitations!
15. What are the alternatives? • Real-time Infrastructure as a Service -> Firebase, RethinkDB • New query languages -> GraphQL, FALCOR • REST-over-WebSocket-kindof APIs -> Emulate REST using JSON payload • Message Queues Protocols -> MQTT, AMQP, STOMP • The good old Remote Procedure Call-> gRPC
16. Message-driven protocol agnostic APIs One architecture to (almost) rule them all
17. Some example messages of our posts API
18. Time to travel and experience new ways
19. Tooling is important too!
20. Introducing AsyncAPI specification • Machine-readable definitions for message-driven APIs. • Protocol-agnostic, so you can use it for APIs that work over MQTT, AMQP, WebSockets, STOMP, etc. • Heavily inspired on OpenAPI. Designed to maintain as much compatibility as possible with it. • Who -> Hitch, an API support platform for API providers • Why -> To be able to provide their services to message-driven APIs
21. The new stuff vs OpenAPI • The path concept disappears, we only need the server URL • New concept, topics ◦ Basically the same of HTTP URIs but protocol-agnostic ◦ Namespace for routing in MQ protocols -> routing key, destination, etc. ◦ Allows to define public and/or subscribe • New concept, messages ◦ A piece of information two or more programs exchange ◦ Describes the payload of the message in both requests and responses+ • New attribute scheme, servers must declare their protocol • Simplified Components Object, only messages, security and schemas
25. Maturity • Young -> Released <6 months ago • Small community -> ~50 GitHub stars • No big (public) project yet • Only one API platform supports it -> Hitch • Tooling -> documentation generator, Node code generator, online editor WIP • Strongly based on OpenAPI -> not reinventing the wheel (too much) • Very specific to MQ protocols but has an extension system
26. Maturity score: first day at school
27. Final thoughts • RESTful APIs are not the best tool out there for Web APIs • Message-driven APIs are being used successfully in other areas • Why not use an unified architecture for all cases? • OpenAPI for message-driven APIs -> AsyncAPI • Not a drop-in replacement! More like an extension • AsyncAPI is in early stages but is a good starting point • The best technology is not the coolest one is the one that solves the problem
28. References and further reading 1. HATEOAS and Hypermedia: a. http://www.amihaiemil.com/2016/05/07/what-is-hateoas.html b. https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/ c. https://vimeo.com/20781278 d. http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven 2. JSON-pure APIs a. https://mmikowski.github.io/the_lie/ b. https://mmikowski.github.io/json-pure/ c. http://jsonapi.org/ 3. Query-efficient APIs a. http://graphql.org/ b. https://netflix.github.io/falcor/ 4. Machine-readable documentation for APIs a. https://www.asyncapi.com/ b. https://www.openapis.org/ 5. Interprocess communication a. https://www.nginx.com/blog/building-microservices-inter-process-communication/
29. Asynchronous APIs Robust APIs for the post-REST world @garcianavalon