A look at common API styles available today, a look back at historical API styles, and guidance for selecting the right API styles for your organization. Deep-dive of HTTP, mentioned in the presentation, can be found at: http://bit.ly/power-http

1. Are REST APIs Still Relevant Today?
16 May 2018 @ GlueCon
James Higginbotham
@launchany

2. 2
Introduction
• API Strategy, Program Execution, Training
– API design
– Microservices
– Containerization
• Recent Projects
– Enterprise IT
– SaaS
– From 100s to 10s of thousands of developers
– Variety of verticals

3. 3
The Simplicity of APIs – Why So Much Conflict?

4. Not about
popularity!

5. 5
Not all APIs are designed to
solve the same problem.

6. 6
APIs Solve a Variety of Problems with Different Contexts
Frontend APIs
(aka Experience API)
Platform APIs
(common, shared business capabilities)
Application APIs
(app-specific logic)
API Consumers/Clients: Web, Mobile, Voice, Backend App
Infrastructure and Operational APIs
(DevOps, Infra)

7. 7
APIs Solve a Variety of Use Cases
Customer
Experience
Worker
Experience
Supplier/Partner
Experience

8. 8
APIs Offer Different Interaction Styles
Request/
Response
Request/
Acknowledge
Batch-Based
Publish/
Subscribe
Message
Streaming

9. 9
APIs: Looking Back at History

10. 10
The Road So Far…
1990s
RPC & Distributed
Object Integration

11. 11
CORBA Architecture

12. 12
The Road So Far…
1990s
RPC & Distributed
Object Integration
2000s
Corp-to-Corp
Integration

13. 13
SOAP Protocol Support: Tunneling through HTTP, SMTP, JMS
Source: https://stackoverflow.com/questions/15705892/what-is-the-purpose-of-ws-addressing

14. 14
SOAP w/ Asynchronous Callbacks
Source: https://docs.oracle.com/cd/E15523_01/web.1111/e15184/asynch.htm

15. 15
The Road So Far…
1990s
RPC & Distributed
Object Integration
2000s
Corp-to-Corp
Integration
2010s
+
Mobile/Data
Integration

16. 16
The Power of the HTTP Protocol for APIs

17. 17
The Basics: URLs, Headers, and HTTP Methods
Method Safe
(Side-
Effect?)
Idempotent
GET Yes Yes
POST No No
PUT No Yes
PATCH No No
DELETE No Yes
HEAD Yes Yes

18. 18
Safe HTTP methods do not modify
resources. e.g. GET, HEAD, OPTIONS
Idempotent HTTP methods can be called
multiple times with the same result.
e.g. GET, HEAD, PUT, DELETE

19. 19
Content Negotiation: Supporting Multiple Content Types
GET https://api.example.com/projects HTTP/1.0
Accept: application/json;q=0.5,application/xml;q=1.0
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Type: application/xml
<project>…</project>
19

20. 20
Language Negotiation: Supporting Multiple Languages
GET https://api.example.com/projects HTTP/1.0
Accept-Language: en;q=0.5,de;q=1.0
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Language: en
<project>
<status>active</status>
<status-display>active</status-display>
</project> 20

21. 21
Language Negotiation: Supporting Multiple Languages
GET https://api.example.com/projects HTTP/1.0
Accept-Language: en;q=0.5,de;q=1.0
HTTP/1.0 200 OK
Date: Tue, 16 June 2015 06:57:43 GMT
Content-Language: de
<project>
<status>active</status>
<status-display>angenommen</status-display>
</project> 21

22. 22
Client-Side Caching: Improving App Performance
Source: https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching

23. 23
Intermediary Caching: Reducing Network Latency
Source: https://www.maxcdn.com/one/visual-glossary/proxy-caching/

24. 24
Conditional Requests: Staying Up-to-date
Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests

25. 25
Concurrency Control: Protecting Resource Integrity with Optimistic Locking
Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests

26. 26
API Design is an architectural
concern that combines
business, product design, and
software engineering

27. 27
Roy Fielding on Architectural Styles
“An architectural style is a coordinated
set of architectural constraints
that restricts the roles/features of
architectural elements and the allowed
relationships among those elements
within any architecture that
conforms to that style.”

28. 28
Roy Fielding on Architectural Styles
“Some architectural styles are often
portrayed as ‘silver bullet’ solutions for all
forms of software. However, a good
designer should select a style that
matches the needs of the particular
problem being solved.”

29. 29
Roy Fielding on Architectural Styles (con’t)
“Choosing the right architectural style for a
network-based application requires an
understanding of the problem domain
and thereby the communication needs
of the application, an awareness of the
variety of architectural styles and the
particular concerns they address…”
- Roy Fielding
https://www.ics.uci.edu/~fielding/pubs/dissertation/software_arch.htm#sec_1_5

30. 30
A Look at Today’s Common API Styles

31. 31
Popular API Styles in 2018

32. 32
GraphQL Example: POST query
Source: https://blog.octo.com/en/graphql-a-new-actor-in-the-api-world/

33. 33
Advantages of GraphQL
Hierarchical
Data Support
Field-Level
Selection
Strong Typing
Good Fit for
Front-End APIs
Introspection

34. 34
Challenges for Some GraphQL Implementors
Limited Endpoint
Security Enforcement
Limited
Ops Tooling
Inconsistencies in
Recommendations
Lack of Flexibility
for Content Types
Lack of
Cacheability

35. 35
Popular API Styles in 2018

36. 36
gRPC: Example Service Definition, Server, and Client
Source: https://grpc.io/docs/quickstart/node.html

37. 37
Advantages of gRPC
High Performance/
Low Latency
Protobuf
Message Format
Code Generation
(client and server)
Bi-Directional
Communication
Built On
HTTP/2

38. 38
Challenges for Some gRPC Implementors
Limited
Error Handling
Limited
Dev/Ops Tooling
Inconsistent Code Gen
Across Languages
Lack of Flexibility
for Content Types
Lack of
Cacheability

39. 39
Popular API Styles in 2018

40. 40
REST APIs are stuck in the land of CRUD

41. 41
Revisiting the REST Constraints
Client-Server Stateless Cache Layered System
Code on Demand
(optional)
Uniform Interface
(resources, representations,
hypermedia)

42. 42
Deep-Dive: REST’s Layered and Cache Constraints
Logging
OAuth
RateLimiting
Caching
Custom
APIImplementation
LoadBalancer
CDN/EdgeCache
Client
Network Infra API Management Layer Your Code
Client
Cache
HTTP HTTP HTTP HTTP

43. 43
HTTP HTTP HTTP
Operationalizing Your API: There is more to your API than code!
Logging
OAuth
RateLimiting
Caching
Custom
APIImplementation
LoadBalancer
CDN/EdgeCache
Client
Network Infra API Management Layer Your Code
Client
Cache
HTTP

44. When APIs Meet Jobs-To-Be-Done
{
…
"_links": {
“self": {"href": "/approval-requests/d796f2d0eb72492bb088"},
“approve": {"href": "/approval-requests/d796f2d0eb72492bb088/approve"},
“decline": {"href": "/approval-requests/d796f2d0eb72492bb088/decline"},
},
…
}

45. 45
Popular API Styles in 2018

46. 46
Webhooks

47. 47
Message Streaming

48. 48
Some Things Change, But Some Stay the Same
+

49. 49
Are REST APIs Still Relevant?

50. 50
Yes!

51. 51
Yes!
Yes, but only if we…

52. 52
#1: We must spend time
understanding the business
problem first, not the technology

53. 53
Capability-Driven API Design

54. 54
#2: We all must become better
educated with what HTTP has to
offer, rather than reinventing the
HTTP protocol over-and-over
(then tunneling them via HTTP)

55. 55
#3. Evolve our tools and
frameworks to better take
advantage of HTTP:
caching, concurrency control,
hypermedia

56. 56
#4. Our thinking must move
”beyond code on the laptop”
and into business use cases,
ops, compliance, and support
concerns

57. 57
#5. Stop using ‘vs.’ and start
using ‘and’ when it comes to
selecting API styles

58. 58
Roy Fielding on Uniform Interface Constraint
“The REST interface is designed to be
efficient for large grain hypermedia data
transfer, optimizing for the common
case of the Web, but resulting in an
interface that is not optimal for other
forms of architectural interaction.”

59. 59
Moving the Mindset From “vs.” to “and”
+
+ +
+ +

60. James Higginbotham
james@launchany.com
@launchany
https://apideveloperweekly.com
Thank you