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

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
    What API
    Your Guide to API Styles
    Zdenek “Z” Nemec
    [email protected]

    View Slide

  2. goodapi.co
    supermodel.io

    View Slide

  3. goodapi.co
    What API Style
    Use for my next application

    View Slide

  4. goodapi.co
    REST vs. GraphQL

    View Slide

  5. goodapi.co
    This is critical review
    Your mileage may vary

    View Slide

  6. goodapi.co
    API Styles

    View Slide

  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

    View Slide

  8. goodapi.co
    API Styles over time

    View Slide

  9. goodapi.co
    Interest over time

    View Slide

  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!

    View Slide

  11. goodapi.co
    Architectural Style

    View Slide

  12. goodapi.co
    Architectural Style
    Set of constraints that
    imply system with
    certain properties
    Applied
    constraints
    imply
    properties

    View Slide

  13. goodapi.co
    Constraint vs. induced property
    Decoupled
    Evolvable
    Stateless
    Reliable Scaleable
    Uniform
    Interface
    Simplicity
    Degraded
    efficiency
    + + + + -

    View Slide

  14. goodapi.co
    Architect

    View Slide

  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.

    View Slide

  16. goodapi.co
    Constraints

    View Slide

  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

    View Slide

  18. goodapi.co
    Listen to your constraints
    “I really like
    colonial
    houses REST
    APIs I think I’ll
    build one…”

    View Slide

  19. goodapi.co
    Two types of constraints
    API Product
    constraints
    API Style
    constraints
    Product owner Architect

    /product constraint/ /style constraint/

    View Slide

  20. goodapi.co
    Product constraint implies style constraint
    External consumers
    Many releases
    Decoupled
    Product owner Architect

    /product constraint/ /style constraint/

    View Slide

  21. goodapi.co
    Constraints induce property
    External consumers
    Many releases
    Decoupled
    Product owner Architect

    /product constraint/ /style constraint/
    Evolvable
    Target system

    /resulting property/

    View Slide

  22. goodapi.co
    API Product constraints

    View Slide

  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

    View Slide

  24. goodapi.co
    Domain
    constraints
    • Governance and domain regulations
    • Environment considerations
    • Domain-specific limitations
    Domain
    of API product

    View Slide

  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

    View Slide

  26. goodapi.co
    Complexity
    constraints
    • Task-structure
    • Unpredictability
    • Size
    • Chaotic
    • Algorithmic
    Complexity
    of API product

    View Slide

  27. goodapi.co
    Constraints
    Business Complexity
    Domain Cultural
    of API product

    View Slide

  28. goodapi.co
    API Style constraints

    View Slide

  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

    View Slide

  30. goodapi.co
    Properties

    View Slide

  31. goodapi.co
    Properties
    Performance Scalability Simplicity Modifiability Visibility
    of API Architectural style
    Portability

    View Slide

  32. goodapi.co
    Properties
    Discoverability Type-safety
    Ease of
    development
    Costs
    of API Architectural style
    Reliability

    View Slide

  33. goodapi.co
    Considerations
    of API style ecosystem
    Community
    Tooling
    Maturity
    Resources
    on API style
    Enterprise
    Readiness
    Ease of
    Publication

    View Slide

  34. goodapi.co
    Every API Product needs
    different properties

    View Slide

  35. goodapi.co
    Recipe

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  39. goodapi.co
    API Styles

    View Slide

  40. goodapi.co
    1. REST

    View Slide

  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

    View Slide

  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

    View Slide

  43. goodapi.co
    2. so-called-REST

    View Slide

  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

    View Slide

  45. goodapi.co
    Use so-called-REST
    if…
    • DON’T
    • Use REST instead
    • Use GraphQL for backend for frontend

    View Slide

  46. goodapi.co
    3. GraphQL

    View Slide

  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

    View Slide

  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

    View Slide

  49. goodapi.co
    4. Apache Kafka

    View Slide

  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

    View Slide

  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

    View Slide

  52. goodapi.co
    5. WebSub

    View Slide

  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

    View Slide

  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

    View Slide

  55. goodapi.co
    6. SOAP

    View Slide

  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

    View Slide

  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

    View Slide

  58. goodapi.co
    7. gRPC

    View Slide

  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

    View Slide

  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

    View Slide

  61. goodapi.co
    8. File

    View Slide

  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

    View Slide

  63. goodapi.co
    Use File Transfer if…
    • The nature of API is not real-time
    • Batch processing
    • Simple solution fast
    Ease of
    development

    View Slide

  64. goodapi.co
    Always decide based on your
    constraints and properties.
    You are unique.

    View Slide

  65. goodapi.co
    Book giveaway

    View Slide

  66. goodapi.co

    View Slide

  67. goodapi.co
    Properties of distributed system

    View Slide

  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

    View Slide

  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

    View Slide