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
   

   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