Tweet
Tweet

Slide 1

Slide 1 text

goodapi.co What API Your Guide to API Styles Zdenek “Z” Nemec [email protected]

Slide 2

Slide 2 text

goodapi.co supermodel.io

Slide 3

Slide 3 text

goodapi.co What API Style Use for my next application

Slide 4

Slide 4 text

goodapi.co REST vs. GraphQL

Slide 5

Slide 5 text

goodapi.co This is critical review Your mileage may vary

Slide 6

Slide 6 text

goodapi.co API Styles

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

goodapi.co API Styles over time

Slide 9

Slide 9 text

goodapi.co Interest over time

Slide 10

Slide 10 text

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!

Slide 11

Slide 11 text

goodapi.co Architectural Style

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

goodapi.co Architect

Slide 15

Slide 15 text

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.

Slide 16

Slide 16 text

goodapi.co Constraints

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

goodapi.co Two types of constraints API Product constraints API Style constraints Product owner Architect /product constraint/ /style constraint/

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

goodapi.co Constraints induce property External consumers Many releases Decoupled Product owner Architect /product constraint/ /style constraint/ Evolvable Target system /resulting property/

Slide 22

Slide 22 text

goodapi.co API Product constraints

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

goodapi.co Constraints Business Complexity Domain Cultural of API product

Slide 28

Slide 28 text

goodapi.co API Style constraints

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

goodapi.co Properties

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

goodapi.co Every API Product needs different properties

Slide 35

Slide 35 text

goodapi.co Recipe

Slide 36

Slide 36 text

goodapi.co API Style Choice of API Style is function of the desired properties and considerations API Style properties API Style considerations + API Style

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

goodapi.co API Styles

Slide 40

Slide 40 text

goodapi.co 1. REST

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

goodapi.co 2. so-called-REST

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

goodapi.co 3. GraphQL

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

goodapi.co 4. Apache Kafka

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

goodapi.co 5. WebSub

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

goodapi.co 6. SOAP

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

goodapi.co 7. gRPC

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

goodapi.co 8. File

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

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

Slide 65

Slide 65 text

goodapi.co Book giveaway

Slide 66

Slide 66 text

goodapi.co

Slide 67

Slide 67 text

goodapi.co Properties of distributed system

Slide 68

Slide 68 text

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

Slide 69

Slide 69 text

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