The Design Of Everyday APIs

Well-designed APIs are a joy to use; poorly-designed APIs are cumbersome, confusing and frustrating, just like everyday things. During this session Arnaud Lauret, the API Handyman, makes a parallel between everyday things design and API design to expose simple but fundamentals design principles.
Is using knobs is better than using buttons? API design is more than REST vs GraphQL vs gRPC vs whatever existing or yet to come API style. Great design can be achieved using any type of API. Would you buy a Kitchen Radar 3000? Are you able to use any washing machine instantly without reading user manual? Why QWERTY layout was invented? Like everyday things, APIs must have a clear purpose, must be used easily by anyone and are constrained by their environment.

Transcript

1. The Design of Everyday APIs
4. What is an API’s purpose?
10. if <power> is high turn magnetron on wait for <duration> turn magnetron off else if <power> is medium cycle = 7s else if <power> is low cycle = 11s else if <power> is thaw cycle = 13s end if for <duration> turn magnetron on wait for <cycle> turn magnetron off wait for <cycle> end for end if heat food at <power> for <duration>
12. USABLE APIS • •
16. GET /wum GET /alarm-clock
17. 1536138951 2018-05-09T09:15:51
18. “countdown”:43020 “alarm”: “08:00”
26. {“prg”:”regular”, “tmp”:”cool”, “rpm”: 1000 “hl”: true} {“program”:”cotton”}
27. 400 BAD REQUEST 400 BAD REQUEST {“message”:”door not closed”}
28. 200 OK 202 ACCEPTED {“finishedIn”:”00:45:00”}
31. 16 G 16
33. G 16 16 16 16
34. G 16 16 16 16 16 16
35. G A 16 16 16 16 16 16 16 16
36. G A 16 16 16 16 16 16 16 16 Prevent errors Aggregate
39. SELF-CONSISTENT
40. SELF-CONSISTENT CONSISTENT ACROSS ORGANIZATION
41. SELF-CONSISTENT CONSISTENT ACROSS ORGANIZATION COMMON PRACTICES & STANDARDS
44. PAGINATION, SORT, FILTER
45. PAGINATION, SORT, FILTER CONTENT NEGOTIATION
46. PAGINATION, SORT, FILTER INTERNATIONALIZATION CONTENT NEGOCIATION
47. PAGINATION, SORT, FILTER INTERNATIONALIZATION CONTENT NEGOCIATION DATA SELECTION
51. “currentPage”: 2, “lastPage”: 10
52. “_links”: { “self”: “/books/123”, “authors”: “/books/123/authors” }
53. OPTIONS /BOOKS 200 OK Allow: GET, POST
57. LATENCY/GRANULARITY
58. LATENCY/GRANULARITY FREQUENCY/WEBHOOKS,STREAMING
59. LATENCY/GRANULARITY FREQUENCY/WEBHOOKS,STREAMING VOLUME/BATCH,BULK
62. SCALABILITY/RATE LIMITING
63. SCALABILITY/RATE LIMITING PERFORMANCE/ASYNCHRONOUS
64. SCALABILITY/RATE LIMITING PERFORMANCE/ASYNCHRONOUS NOT 24-7/NO GO