Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

What API: Your Guide to API Styles

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

Z

October 23, 2019
Tweet

More Decks by Z

Other Decks in Programming

Transcript

  1. 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
  2. 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!
  3. goodapi.co Architectural Style Set of constraints that imply system with

    certain properties Applied constraints imply properties
  4. goodapi.co Constraint vs. induced property Decoupled Evolvable Stateless Reliable Scaleable

    Uniform Interface Simplicity Degraded efficiency + + + + -
  5. 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.
  6. 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
  7. goodapi.co Two types of constraints API Product constraints API Style

    constraints Product owner Architect /product constraint/ /style constraint/
  8. goodapi.co Product constraint implies style constraint External consumers Many releases

    Decoupled Product owner Architect /product constraint/ /style constraint/
  9. goodapi.co Constraints induce property External consumers Many releases Decoupled Product

    owner Architect /product constraint/ /style constraint/ Evolvable Target system /resulting property/
  10. 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
  11. goodapi.co Domain constraints • Governance and domain regulations • Environment

    considerations • Domain-specific limitations Domain of API product
  12. 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
  13. 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
  14. goodapi.co API Style Choice of API Style is function of

    the desired properties and considerations API Style properties API Style considerations + API Style
  15. 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
  16. 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
  17. 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
  18. 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
  19. 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
  20. 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
  21. 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
  22. 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
  23. 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
  24. 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
  25. 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
  26. 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
  27. 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
  28. 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
  29. 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
  30. 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
  31. goodapi.co Use File Transfer if… • The nature of API

    is not real-time • Batch processing • Simple solution fast Ease of development
  32. 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
  33. 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