RESOLVING THE API DEVELOPER’S DILEMMA
@ROBDCROWLEY | ROBDCROWLEY
Slide 2
Slide 2 text
▪ A TOUR OF API STYLES OVER TIME
▪ CONSTRAINTS AND INDUCED PROPERTIES
▪ MYTH BUSTING
▪ SAMPLE SCENARIOS
Slide 3
Slide 3 text
No content
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
No content
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
’
Slide 10
Slide 10 text
No content
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
No content
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
’
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
’
’
Slide 19
Slide 19 text
’
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
No content
Slide 22
Slide 22 text
No content
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
No content
Slide 25
Slide 25 text
Properties are induced by the set of
constraints within an architecture
Slide 26
Slide 26 text
CUSTOMER / BUSINESS / PRODUCT REQUIREMENTS
Slide 27
Slide 27 text
IMPLICATIONS OF DISTRIBUTED SYSTEM COMPLEXITY, 8 FALLACIES,
EVOLUTIONARY REQUIREMENTS
Slide 28
Slide 28 text
SYSTEM OF WORK, CONWAY’S LAW, KNOWLEDGE / EXPERTISE
Slide 29
Slide 29 text
⇒
Slide 30
Slide 30 text
No content
Slide 31
Slide 31 text
“ ”
Slide 32
Slide 32 text
’
Slide 33
Slide 33 text
“
”
Slide 34
Slide 34 text
“
”
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
No content
Slide 37
Slide 37 text
No content
Slide 38
Slide 38 text
No content
Slide 39
Slide 39 text
’
Slide 40
Slide 40 text
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
Slide 41
Slide 41 text
No content
Slide 42
Slide 42 text
▪ API STYLES ADDRESS DIFFERENT PROBLEM SPACES
▪ RESTISH APIS WOULD MOST LIKELY BE BETTER AS GRAPHQL OR RPC
▪ gRPC IS PERFECT FOR SYCHRONOUS COMMUNICATIONS BETWEEN
INTERNAL SERVICES
Slide 43
Slide 43 text
“ “
Slide 44
Slide 44 text
No content
Slide 45
Slide 45 text
No content
Slide 46
Slide 46 text
No content
Slide 47
Slide 47 text
No content
Slide 48
Slide 48 text
No content
Slide 49
Slide 49 text
No content
Slide 50
Slide 50 text
No content
Slide 51
Slide 51 text
No content
Slide 52
Slide 52 text
▪ 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
Slide 53
Slide 53 text
“ “
Slide 54
Slide 54 text
⇒
Slide 55
Slide 55 text
No content
Slide 56
Slide 56 text
GRAPHQL ENABLES EACH CLIENT TO RETRIEVE EXACTLY THE DATA IT
REQUIRES IN A SINGLE ROUND TRIP TO THE SERVER
Slide 57
Slide 57 text
No content
Slide 58
Slide 58 text
No content
Slide 59
Slide 59 text
No content
Slide 60
Slide 60 text
No content
Slide 61
Slide 61 text
No content
Slide 62
Slide 62 text
▪ 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
CASES THOROUGHLY
Slide 63
Slide 63 text
“
“
Slide 64
Slide 64 text
No content
Slide 65
Slide 65 text
No content
Slide 66
Slide 66 text
No content
Slide 67
Slide 67 text
▪ 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
Slide 68
Slide 68 text
No content
Slide 69
Slide 69 text
No content
Slide 70
Slide 70 text
No content
Slide 71
Slide 71 text
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.
’
Slide 72
Slide 72 text
No content
Slide 73
Slide 73 text
Make a system evolvable by paying
attention to the interfaces.
Slide 74
Slide 74 text
No content
Slide 75
Slide 75 text
- 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
team
- Integrate front and back ends
- Ship
- Repeat
Slide 76
Slide 76 text
▪ 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
Slide 77
Slide 77 text
“
“
Slide 78
Slide 78 text
No content
Slide 79
Slide 79 text
No content
Slide 80
Slide 80 text
No content
Slide 81
Slide 81 text
▪ API DESIGN SKILLS ARE TABLE STAKES IRRESPECTIVE OF STYLE
▪ DESIGING A REST API FOLLOWS OUTSIDE-IN FLOW
▪ GRAPHQL DELAYS THIS MOMENT TO PROFILING QUERIES
Slide 82
Slide 82 text
No content
Slide 83
Slide 83 text
CRUD. SINGLE CLIENT THAT USES ALL FIELDS. USE CASE THAT IS WELL
SUITED TO REST.
Slide 84
Slide 84 text
AGGREGATE DATA FROM MULTIPLE SOURCES INTO ONE CONVENIENT
API. PERFECT USE CASE FOR GRAPHQL.
Slide 85
Slide 85 text
No content
Slide 86
Slide 86 text
SINGLE CLIENT. API IS STATIC AND WELL UNDERSTOOD. USE CASE WELL
SUITED TO GRPC (I’M STILL EXPERIMENTING THOUGH!)
Slide 87
Slide 87 text
No content
Slide 88
Slide 88 text
POLYGLOT ENVIRONMENT. GRPC IS PERFECT FOR SYCHRONOUS
COMMUNICATION BETWEEN INTERNAL MICROSERVICES.