What API: Your Guide to API Styles

Good news everyone, It is no longer just REST vs. GraphQL! Additional API styles like Kafka, gRPC, and others are getting more and more traction and stirring the stalled waters of API type decision-making. In 2019 there are more API styles to choose from than ever. But how should you decide which one is right if you are a software architect or an API product owner?

Building on the 2018’s discussion of which one is the best (REST or GraphQL), this talk will present you the critical review of eight (8) popular API styles. But more importantly, you will learn the decision-making framework for selecting the right style for your next project! The talk will come with real-world examples from both Fortune 500 companies and cutting-edge startups alike to illustrate further serve as the reference for decisions

Transcript

1. goodapi.co What API Your Guide to API Styles Zdenek “Z” Nemec z@goodapi.co
2. goodapi.co supermodel.io
3. goodapi.co What API Style Use for my next application
4. goodapi.co REST vs. GraphQL
5. goodapi.co This is critical review Your mileage may vary
6. goodapi.co API Styles
7. goodapi.co API styles of interest Web APIs 1. REST APIs 2. so-called REST APIs Query APIs (RPC) 3. GraphQL Publish-Subscribe APIs 4. Kafka 5. WebSub RPC APIs 6. SOAP 7. gRPC 8. Flat File NOTE 2: Many of the Web, Query and RPC APIs also offers pub-sub functionality NOTE 1: ”API Style” is either API Architectural Style, Protocol, or Framework
8. goodapi.co API Styles over time
9. goodapi.co Interest over time
10. goodapi.co Paradigm Shift 1. CUSTOMER-SPECIFIC APIS 2. GENERIC APIS 3. HARMONIZED APIS 4. AUTONOMOUS APIS one-to-many one-to-one many-to-many machine-to-machine l C P l C P l C l C l C P l C l C P P l C P l C l C P P 3P BREAKTHROUGH ANNOUNCEMENT SOON!
11. goodapi.co Architectural Style
12. goodapi.co Architectural Style Set of constraints that imply system with certain properties Applied constraints imply properties
13. goodapi.co Constraint vs. induced property Decoupled Evolvable Stateless Reliable Scaleable Uniform Interface Simplicity Degraded efficiency + + + + -
14. goodapi.co Architect
15. goodapi.co Role of an Architect Architect knows something about everything, an engineer knows everything about one thing. Understand many paradigms and pick the right one for the task based on the product constraints.
16. goodapi.co Constraints
17. goodapi.co Colonial architecture “I really like colonial houses, I think I’ll build one…” Houses were colonial because of the colonists were colonial and had colonial constraints
18. goodapi.co Listen to your constraints “I really like colonial houses REST APIs I think I’ll build one…”
19. goodapi.co Two types of constraints API Product constraints API Style constraints Product owner Architect /product constraint/ /style constraint/
20. goodapi.co Product constraint implies style constraint External consumers Many releases Decoupled Product owner Architect /product constraint/ /style constraint/
21. goodapi.co Constraints induce property External consumers Many releases Decoupled Product owner Architect /product constraint/ /style constraint/ Evolvable Target system /resulting property/
22. goodapi.co API Product constraints
23. goodapi.co Business constraints • Business & product requirements • Product use cases • Customer constraints • Time to market • Company strategy • API program funding • Costs Business of API product
24. goodapi.co Domain constraints • Governance and domain regulations • Environment considerations • Domain-specific limitations Domain of API product
25. goodapi.co Cultural constraints • Conway's law • Knowledge, education • Investment in existing infrastructure (e.g. ESB) • Human Resources • Leadership support • Trends, hype, peer-pressure “Product errors reflect organizational errors“ — Elon Musk Cultural of API product
26. goodapi.co Complexity constraints • Task-structure • Unpredictability • Size • Chaotic • Algorithmic Complexity of API product
27. goodapi.co Constraints Business Complexity Domain Cultural of API product
28. goodapi.co API Style constraints
29. goodapi.co Constraints Client-server Layered System Stateless Cacheable of API style (for example REST) Code-on-demand Uniform interface NOTE: Uniform Interface has four sub-constraints: Identification of Resources, Resource Representations, Self-descriptive Messages, HATEOAS
30. goodapi.co Properties
31. goodapi.co Properties Performance Scalability Simplicity Modifiability Visibility of API Architectural style Portability
32. goodapi.co Properties Discoverability Type-safety Ease of development Costs of API Architectural style Reliability
33. goodapi.co Considerations of API style ecosystem Community Tooling Maturity Resources on API style Enterprise Readiness Ease of Publication
34. goodapi.co Every API Product needs different properties
35. goodapi.co Recipe
36. goodapi.co API Style Choice of API Style is function of the desired properties and considerations API Style properties API Style considerations + API Style
37. goodapi.co Example Performance Scalability Simplicity Modifiability Visibility Portability Discoverability Type-safety Ease of development Costs Reliability Community Tooling Maturity Resources on API style Enterprise Readiness Ease of Publication REST
38. goodapi.co Example Performance Scalability Simplicity Modifiability Visibility Portability Discoverability Type-safety Ease of development Costs Reliability Community Tooling Maturity Resources on API style Enterprise Readiness Ease of Publication GRAPHQL
39. goodapi.co API Styles
40. goodapi.co 1. REST
41. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style REST Ease of Publication
42. goodapi.co Use REST if… • Build system that lasts • In need of content negotiation (language) • Use multiple media types • Precise authentication, authorization rate limiting • Interlink resources between APIs • Care about scaleability Scalability Simplicity Modifiability Reliability
43. goodapi.co 2. so-called-REST
44. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface so-called-REST Ease of Publication
45. goodapi.co Use so-called-REST if… • DON’T • Use REST instead • Use GraphQL for backend for frontend
46. goodapi.co 3. GraphQL
47. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style Client-server Stateless Cacheable Layered system Code-on-demand GraphQL Uniform interface Ease of Publication
48. goodapi.co Use GraphQL if… • Talking to yourself (frontend–backend) • Instead of so-called-REST • Short term projects • Uncertain use-cases • Just access data without the need for infra caching • Amazing DX with little effort Type-safety Ease of development Costs Tooling Community
49. goodapi.co 4. Apache Kafka
50. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style Client-server Stateless Cacheable Layered system Code-on-demand Apache Kafka Uniform interface Ease of Publication
51. goodapi.co Use Kafka if… • You need a publish-subscribe async streaming API • You will benefit from a message broker • Passing messages that must not be lost • You have a strong JAVA culture • You do not mind the immature design lifecycle • You are building internal only API Performance Scalability Reliability
52. goodapi.co 5. WebSub
53. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style WebSub Ease of Publication
54. goodapi.co Use WebSub if… • You need a publish-subscribe API • The API is/might be public • If the API should be productized • If you need add-on to existing API • Looking for a mature style that works well with REST APIs • Language -agnostic environment Modifiability Discoverability
55. goodapi.co 6. SOAP
56. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Discoverability Reliability Portability Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style SOAP Ease of Publication Visibility NOTE: With HTTP transport layer
57. goodapi.co Use SOAP if… • Customer asks for it • One-to-one scenario (point-to-point) integration • You have existing infrastructure and culture Enterprise Readiness
58. goodapi.co 7. gRPC
59. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style Ease of Publication gRPC
60. goodapi.co Use gRPC if… • You need extreme network efficiency • Fastest fully duplex asynchronous communication • You are not building Web application • You do not need a message broker – e.g. services are communicating directly Performance Type-safety
61. goodapi.co 8. File
62. goodapi.co API Style constraints, properties and considerations Performance Scalability Simplicity Modifiability Visibility Discoverability Reliability Portability Client-server Stateless Cacheable Layered system Code-on-demand Uniform interface Type-safety Ease of development Costs Maturity Enterprise Readiness Tooling Community Resources on API style File Transfer Ease of Publication
63. goodapi.co Use File Transfer if… • The nature of API is not real-time • Batch processing • Simple solution fast Ease of development
64. goodapi.co Always decide based on your constraints and properties. You are unique.
65. goodapi.co Book giveaway
66. goodapi.co
67. goodapi.co Properties of distributed system
68. goodapi.co REST Constraints & induced Properties 1.Client-Server 2.Stateless 3.Cacheable 4.Layered System 5.Code on Demand (optional) 6.Uniform Interface 1.Identification of Resources 2.Resource Representations 3.Self-descriptive Messages 4.HATEOAS 1.Performance 2.Scalability 3.Simplicity 4.Modifiability 5.Visibility 6.Portability 7.Reliability
69. goodapi.co REST Constraints & induced Properties in so-called-REST APIs 1.Client-Server 2.Stateless 3.Cacheable 4.Layered System 5.Code on Demand (optional) 6.Uniform Interface 1.Identification of Resources 2.Resource Representations 3.Self-descriptive Messages 4.HATEOAS 1.Performance 2.Scalability 3.Simplicity 4.Modifiability 5.Visibility 6.Portability 7.Reliability