GraphQL, gRPC, REST and WebHooks are among a bewildering array of technologies and architectural styles that are available to API developers today. Presented with such myriad options, how can we be confident of making an appropriate decision for the problem at hand? In search of guidance, developers often turn to online communities. This can exacerbate the problem as discussions about API styles often descend into statements about the superiority of one approach over another being presented as universal truths. Such comments invariably earn emotive rebuttals that also lack sufficient nuance. The result of such exchanges is increased confusion and uncertainty. Join me on a tour of these API styles where we will cut through this noise, demonstrate where each style shines (plus where they don't!) and ultimately resolve this dilemma of choice.
In this session we'll take an in-depth look at API design; the best practices that have evolved; the game changing supporting technologies that are now available including HTTP/2; and most importantly what you need to do to deliver a world class developer experience:
- How to determine the suitability of an API style for your application context. Don't be a victim of technology hype!
- What is required to support graceful evolution of the API contract including the potential implications of both Hyrum's Law and the Law of Implicit Interfaces
- Understand the supporting toolchains and technologies that dovetail with each API style.
- The importance of treating your API as a product with an unwavering focus on improving the ease of consumption for your clients.
By the end of the session, you will not only understand the concepts underpinning these various API styles but also have the knowledge to put them into practice. If you want to take to your API design expertise to the next level,
RESOLVING THE API DEVELOPER’S DILEMMA
@ROBDCROWLEY | ROBDCROWLEY
▪ A TOUR OF API STYLES OVER TIME
▪ CONSTRAINTS AND INDUCED PROPERTIES
▪ MYTH BUSTING
▪ SAMPLE SCENARIOS
Properties are induced by the set of
constraints within an architecture
CUSTOMER / BUSINESS / PRODUCT REQUIREMENTS
IMPLICATIONS OF DISTRIBUTED SYSTEM COMPLEXITY, 8 FALLACIES,
SYSTEM OF WORK, CONWAY’S LAW, KNOWLEDGE / EXPERTISE
If an API is mostly actions, maybe it
should be RPC. If an API is mostly CRUD
and is manipulating related data, maybe
it should be REST
▪ API STYLES ADDRESS DIFFERENT PROBLEM SPACES
▪ RESTISH APIS WOULD MOST LIKELY BE BETTER AS GRAPHQL OR RPC
▪ gRPC IS PERFECT FOR SYCHRONOUS COMMUNICATIONS BETWEEN
▪ THERE ARE MANY KINDS OF CACHES: CLIENT, SEVER AND NETWORK
▪ HIGHLY CUSTOMIZABLE APIS BENEFIT LESS FROM HTTP CACHING
▪ IF NETWORK CACHING IS VALUABLE THEN CONSIDER REST
▪ BEST PRACTICES ARE STILL EMERGING FOR GRAPHQL AND gRPC
GRAPHQL ENABLES EACH CLIENT TO RETRIEVE EXACTLY THE DATA IT
REQUIRES IN A SINGLE ROUND TRIP TO THE SERVER
▪ WITH HTTP/1.X THE COST OF A HANDSHAKE WAS HIGH
▪ HTTP/2 REMOVES THE NEED FOR COMPOUND DOCUMENTS
▪ SERVER PUSH CREATES NEW POSSIBILITIES BUT PROFILE USE
▪ DON’T ADD REQUIRED INPUTS
▪ DON’T REMOVE OUTPUTS OR MAKE THEM OPTIONAL
▪ DON’T CHANGE THE TYPE OF A FIELD
▪ FOLLOW THE ROBUSTNESS PRINCIPLE / POSTEL’S LAW
With a sufficient number of users of
an API, it does not matter what you
promise in the contract: all observable
behaviours of your system will be
depended on by somebody.
Make a system evolvable by paying
attention to the interfaces.
- Front end and back end teams
agree on schema.
- UI is developed using mocked data
based on schema
- API is built out with any changes
being communicated to front end
- Integrate front and back ends
▪ IS A TECHNIQUE TO MANAGE BREAKING CHANGES
▪ SHOULD BE A LAST RESORT, PREFER GRACEFUL EVOLUTION
▪ IS NOT A SUBSTITUTE FOR COMMUNICATING WITH USERS
▪ DOES NOT PROTECT AGAINST CONSUMERS DEPENDING ON
IMPLICIT INTERFACE BEHAVIOUR
▪ API DESIGN SKILLS ARE TABLE STAKES IRRESPECTIVE OF STYLE
▪ DESIGING A REST API FOLLOWS OUTSIDE-IN FLOW
▪ GRAPHQL DELAYS THIS MOMENT TO PROFILING QUERIES
CRUD. SINGLE CLIENT THAT USES ALL FIELDS. USE CASE THAT IS WELL
SUITED TO REST.
AGGREGATE DATA FROM MULTIPLE SOURCES INTO ONE CONVENIENT
API. PERFECT USE CASE FOR GRAPHQL.
SINGLE CLIENT. API IS STATIC AND WELL UNDERSTOOD. USE CASE WELL
SUITED TO GRPC (I’M STILL EXPERIMENTING THOUGH!)
POLYGLOT ENVIRONMENT. GRPC IS PERFECT FOR SYCHRONOUS
COMMUNICATION BETWEEN INTERNAL MICROSERVICES.