The document discusses three flavors or patterns of APIs: Resource API, System/Use Case API, and Consumer API. A Resource API has a 1-to-1 mapping between services and APIs, requires knowledge of data models, and has low complexity for providers but high complexity for consumers. A System/Use Case API aggregates services into APIs built around use cases, requires some data model knowledge, and has medium complexity for both providers and consumers. A Consumer API is designed purely around consumer needs, hides data models and integration details, and has high complexity for providers but low complexity for consumers.
1. Three Flavours of APIs
aka API Design Patterns
Chris Phillips
IBM Master Inventor
2. 2IBM Think 2020
Who I am
Chris Phillips
IBM Master Inventor
API Guru
Author of the API Connect White Paper for v10 and v2018
IBM Cloud Integration Architect for the WW SWAT Team
IBM 12.5 years
Nearly 11 years in Integration
Blog: http://chrisphillips-cminion.github.io
LinkedIn: https://www.linkedin.com/in/chrisjphillips
Twitter: @cminion
2
5. The exposure of a function to disparate systems
What is an API?
6. Other terms I have heard
• Designed to simplify the consumption of functions (Pure-ism)
• Has a specification
• Designed to provide as much information as needed to
consume it
• Just another name for a service
• Designed to get someone promoted
What is an API?
7. • What is the objective?
• Simplify onboarding
• Tracking consumption
• Self Service
• Speed to market
• What is your budget?
• Money
• Personnel
• Time
Questions you need to ask yourself
Try not to ask yourself
• What are your KPIs?
8. System API /
Use Case API
Three Flavours of APIs
Resource API Consumer API
9. Three Flavours of APIs
Resource API
• 1 - 1 mapping between Service to API
• No interface change
• No data model change
• Requires knowledge of the data model before it can be consumed
IntegrationSystem
Resource API
ValidateSecurity
Rate Limiting Docs & Spec
👩
🏼
💻
👩
🏼
💻
👩
🏼
💻
10. Three Flavours of APIs
System or Use Case API
IntegrationSystem
• Many - Many mapping between APIs
• Designed around the services available
• APIs built around use cases and need
• Business need fulfilling and aggregation
• Minimal data model change
• Requires knowledge of the data model before it can be consumed
System API / Use Case API
Map
Interface Change
Validate
Security
Rate Limiting
Docs & Spec👩
🏼
💻
👩
🏼
💻
👩
🏼
💻
11. IntegrationSystem
Three Flavours of APIs
Consumer API
👩
🏼
Consumer API
Map
Interface Change
Validate
Security
Rate Limiting
Docs & Spec👩
🏼
👩
🏼
• Purist
• Consumer APIs are not for a single Consumer
• Consumer has no knowledge of the downstream system they are invoking
• Designed around easy completion of Use Cases
• Data Model is restricted to exactly what is needed
• Potentially complex data model changes
• Consumer does not know about interface changes or mapping in the API
12. Three Flavours of APIs
Summary
👩
👩
🏼
💻
👩
🏼
IntegrationSystem
System API / Use Case API
Map
Interface Change
Validate
Security
Rate Limiting
Docs & Spec
Consumer API
Map
Interface Change
Validate
Security
Resource API
ValidateSecurity
Rate Limiting Docs & Spec
Rate Limiting
Docs & Spec
13. Three Flavours of APIs
System API / Use Case APIResource API Consumer API
Cost to Provider Low
Complexity to Provider Low
Complexity to Consumer High
Cost to Provider Medium
Complexity to Provider Medium
Complexity to Consumer Medium
Cost to Provider High
Complexity to Provider High
Complexity to Consumer Low
Pros
• Quick
• Minimal Design
• Resource Focused
Cons
• Not really an API
• Assumes Prior Knowledge of
data models and integration
layer
Pros
• Some simplification for
consumers
Cons
• Assumes Prior Knowledge of
data models and integration
layer
Pros
• Designed around the consumer
need
• Quick to consume
• Purest
Cons
• Expensive
• Lots of Design
Examples
• Philips Hue
• Cloudant
Examples
• GraphQL
Examples
• PSD2
• Facebook
• Twitter
14. Three Flavours of APIs
System API / Use Case APIResource API Consumer API
Cost to Provider Low
Complexity to Provider Low
Complexity to Consumer High
Cost to Provider Medium
Complexity to Provider Medium
Complexity to Consumer Medium
Cost to Provider High
Complexity to Provider High
Complexity to Consumer Low
Pros
• Quick
• Minimal Design
• Resource Focused
Cons
• Not really an API
• Assumes Prior Knowledge of
data models and integration
layer
Pros
• Some simplification for
consumers
Cons
• Assumes Prior Knowledge of
data models and integration
layer
Pros
• Designed around the consumer
need
• Quick to consume
• Purest
Cons
• Expensive
• Lots of Design
Examples
• Philips Hue
• Cloudant
Examples
• GraphQL
Examples
• PSD2
• Facebook
• Twitter
15. How do I know which to
choose
• Who is your long-term target audience?
• How big is your long-term target audience?
• How skilled is your target audience?
• How many APIs need to be delivered to be considered
useful?
• How many APIs are going to be delivered?