Well-designed APIs are a joy to use; poorly-designed APIs are cumbersome, confusing and frustrating. API design quality is what separate success from failure. But what is a “well-designed” API or a “poorly-designed” one? That’s a tricky question, but we can answer it with another one: how do you judge the quality of an everyday thing such as a microwave oven, a door or remote control? Yes, API designer can learn a great deal from observing the design of everyday things and having some basic design knowledge. This session aims to make a parallel between API design and everyday things design to expose simple but fundamentals design principles that any API designer should be aware of to create well-designed APIs using any type of API.

1. The Design of
Everyday APIs
Arnaud Lauret @apihandyman
Natixis

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
● Straightforward design
● Predictable design

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. G16 16
16 16

34. G16 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