Upgrade to Pro — share decks privately, control downloads, hide ads and more …

What API: Your Guide to API Styles

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
October 23, 2019

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

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

October 23, 2019
Tweet

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