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
Alfresco TTL#157 - Troubleshooting Made Easy: Deciphering Alfresco mTLS Confi...
Austin API Summit 2018: Are REST APIs Still Relevant Today?
1. Are REST APIs Still Relevant Today?
13 June 2018 @ Austin API Summit
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.
4. 4
APIs Solve a Variety of Use Cases
Customer
Experience
Worker
Experience
Supplier/Partner
Experience
14. 14
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
15. 15
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>
15
16. 16
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> 16
17. 17
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> 17
27. 27
Challenges for Some GraphQL Implementors
Limited Endpoint
Security Enforcement
Limited
Ops Tooling
Inconsistencies in
Recommendations
Lack of Flexibility
for Content Types
Lack of
Cacheability
29. 29
gRPC: Example Service Definition, Server, and Client
Source: https://grpc.io/docs/quickstart/node.html
30. 30
Advantages of gRPC
High Performance/
Low Latency
Protobuf
Message Format
Code Generation
(client and server)
Bi-Directional
Communication
Built On
HTTP/2
31. 31
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
34. 34
Revisiting the REST Constraints
Client-Server Stateless Cache Layered System
Code on Demand
(optional)
Uniform Interface
(resources, representations,
hypermedia)
35. 35
Deep-Dive: REST’s Layered and Cache Constraints
Logging
AccessManagement
RateLimiting
Caching
Custom
APIImplementation
LoadBalancer
CDN/EdgeCache
Client
Network Infra API Management Layer Your Code
Client
Cache
HTTP HTTP HTTP HTTP
36. 36
HTTP HTTP HTTP
Operationalizing Your API: There is more to your API than code!
Logging
AccessManagement
RateLimiting
Caching
Custom
APIImplementation
LoadBalancer
CDN/EdgeCache
Client
Network Infra API Management Layer Your Code
Client
Cache
HTTP
44. 44
#1: We must spend time to
understand the business
problem first, not the
technology
45. 45
#2: We all must become better
educated with what HTTP has
to offer, rather than reinventing
the HTTP protocol over-and-
over (then tunneling it via
HTTP)
46. 46
#3. Evolve our tools and
frameworks to better take
advantage of HTTP:
caching, concurrency control,
hypermedia
47. 47
#4. Our thinking must move
”beyond code on the laptop”
and into business use cases,
ops, compliance, and support
concerns
48. 48
#5. Stop using ‘vs.’ and start
using ‘and’ when it comes to
selecting API styles
If it is just about Google search volume, REST wins – thanks for listening!
But, it isn’t just about search volume…
Our APIs also support different use cases indirectly. That, combined with the context in which they are used (external, internal, operational) and interaction styles results in a large variety of API contexts we must support. It stands to reason then that not any one API style can meet all of these needs.
Let’s step back and review some history, see how we solved for these needs in the past, and how modern API styles can help us solve today’s needs
Before we look at today’s API styles, it is important to look over our shoulder at some recent styles that we have used (and some continue to use)
Early days we used RPC and CORBA – distributed components for system interoperability needs
ORB (Object Request Broker) was middleware ($$$) that handled network protocols and offered code generation tools based on IDL (interface definition language).
Solved the need to bridge various programming languages and try to achieve system-to-system interoperability. It worked – to a point – but still struggled with interoperability along with the fragility of integrating directly with code from our objects
Enter SOAP – distributed computing over HTTP driven by integration needs
JSON + HTTP – distributed computing for billions of devices
HTTP Methods are NOT about CRUD
Q-factors allow for specifying multiple supported types
English if German not supported
Otherwise, we can receive German
angenommen = ”active” in German
All tunneled through HTTP/POST
Started by who? Facebook – the company that stores a huge world-wide graph of profiles and relationships!
Github adopted because – they have a huge graph of repositories, owners, and corresponding relationships!
Reference CORBA, show that middleware was removed in favor of OSS generators, HTTP/2 used for protocol
GraphQL ignores the web and just uses HTTP POST for tunneling – much like SOAP
Based on some case studies I reviewed, there have been a few challenges encountered:
Dev/Ops tooling – the optimum path for GraphQL is for front-end developers. Little attention is paid to operational concerns, side-steps many of the benefits of HTTP
Cacheability – POST used for all queries, no etag support
No concurrency support; Currently JSON-based
HTTP/2 POST
Bi-directional support
Reference CORBA, show that middleware was removed in favor of OSS generators, HTTP/2 used for protocol
gRPC depends highly on code generation and ties clients tightly to server code, like CORBA did. Interoperability became an issue as people deviated
Based on some case studies I reviewed, there have been a few challenges encountered:
Dev/Ops tooling – the optimum path for gRPC is for backend developers. Little attention is paid to front-end devs and operational concerns
Relies on the strength of code generators and community that drives them
As I train organizations, I see the same common problem: we are stuck in CRUD.
If we can build CRUD APIs in 15 minutes, we tend to push implementation concerns and data joining to the consumer-side.
We need to ask ourselves if we value our API consumers. They don’t want to manage a database over HTTP.
Client-Server and Stateless are common.
Uniform Interface, Cache, Layered start to differentiate REST from others
If the layered constraint is properly applied, middleware can be added to load balance requests, apply rate limits, enforce security, add caching.
This is only possible if we utilize HTTP to the fullest!
When we tunnel through HTTP using POST, as we do with GraphQL and gRPC, we make this more difficult to operationalize
Without it, this is pushed to the codebase or, at best, the edge of the API rather than the edge of the network (closest to the devices)
BTW, this diagram reveals a big reality check: there is more to writing an API than your code! You must pay attention to the operationalization side as well!
From caching to security, rate limiting, load balancing – all of it!
A fancy new API style may or may not be easy to make production-ready!
More FREEDOM for clients to be extended with new capabilities at runtime - with limited or no changes by the client
Requires us to understand HTTP deeply and apply THOUGHTFUL design considerations
gRPC learned from CORBA, moved to HTTP/2 for scale
GraphQL blends SOAP with HTTP+JSON
Let’s consider the kinds of software we see emerging, and how APIs will drive
As we talked about earlier – HTTP is powerful, but only if we seek to understand it better
Our tools, frameworks must adapt to use more of the HTTP protocol. Some are designed to do so through plugins/extensions. Others, not so much
We must consider all areas of software design and architecture – especially going beyond the code that runs on our laptop
Vim vs. Emacs
.Net vs. Java
REST vs. GraphQL
REST is a great foundation for many shared APIs when the constraints and patterns fit – resources, course grained, built directly upon HTTP
But it doesn’t have to be the only choice