Designing APIs for Humans - Write the Docs 2016

Transcript

1. Designing APIs for Humans Kyle Fuller
4. Focussed on Collaboration
5. # GET /message + Response 200 (text/plain) Hello World!
6. Think Before you Code
7. Your API
8. API Facade
9. "The best API designs tends to be those that are understood by everybody involved in the API- lifecycle"
11. Designing our first API
12. Cluedo
13. # Cluedo
14. # Cluedo The classic game of whodunit! To solve the mystery, you must find out who committed the crime, what was the murder weapon used, and in which room the crime was committed.
15. ## The Game You will be dealt some cards. You can immediately eliminate these characters, rooms and weapons from your investigation. During the game, move from room to room to make your enquiries. Once inside a room, make a "suggestion" on your turn by calling a character and a weapon into the room. ...
18. ## Game
19. ## Game ### Begin play
20. ## Game ### Begin play A player can begin the game as soon as there are at least two players. No new players can join the game once it is started.
21. ## Game [/game/{id}] ### Begin play A player can begin the game as soon as there are at least two players. No new players can join the game once it is started.
22. ## Game [/game/{id}] + Parameters + id - Unique identifier for a game
23. ### Begin play [PUT] A player can begin the game as soon as there are at least two players. No new players can join the game once it is started.
24. ### Begin play [PUT] A player can begin the game as soon as there are at least two players. No new players can join the game once it is started. + Response 204
25. Resource: Game Action: Begin play • Example HTTP Response
26. Human Friendly
27. Machine Readable
28. $ drafter -f json cluedo.apib
29. { "element": "transition", "meta": { "title": "Begin play" }, "content": [ { "element": "copy", "content": "A player can begin the game as soon as there are at least two players. No new players can join the game once it is started." } ] }
30. Prototyping
31. Mock-server
32. $ curl -I -X PUT http://private-ceaf6d-cluedo.apiary-mock.com/game/c9d60ae4 HTTP/1.1 204 No Content Server: Cowboy Connection: keep-alive X-Apiary-Ratelimit-Limit: 120 X-Apiary-Ratelimit-Remaining: 116 Access-Control-Allow-Origin: * Access-Control-Allow-Methods: OPTIONS,GET,HEAD,POST,PUT,DELETE,TRACE,CONNECT Access-Control-Max-Age: 10 X-Apiary-Transaction-Id: 56d84b8058d1380b00f6593f Content-Length: 0 Date: Thu, 03 Mar 2016 14:34:40 GMT Via: 1.1 vegur
33. $ curl http://private-ceaf6d-cluedo.apiary-mock.com/game/c9d60ae4 { "players": [ { "name": "scarlet", "position": { "x": 12, "y": 6, "room": "ballroom" } } ], "status": "unstarted" }
34. Traffic Inspector
38. Implementation
39. 404 "Not Found"
40. How do you test your API documentation?
41. You Don't.
42. Dredd https://github.com/apiaryio/dredd
43. $ dredd cluedo.apib https://localhost:8080
44. $ dredd cluedo.apib https://localhost:8080 info: Beginning Dredd testing... pass: GET /game/c9d60ae4 duration: 10ms pass: PUT /game/c9d60ae4 duration: 8ms complete: 2 passing, 0 failing, 0 errors, 0 skipped, 2 total complete: Tests took 18ms
45. $ dredd cluedo.apib https://localhost:8080 info: Beginning Dredd testing... pass: GET /game/c9d60ae4 duration: 10ms fail: PUT /game/c9d60ae4 duration: 8ms fail: PUT /game/c9d60ae4 duration: 10ms fail: statusCode: Status code is not '204' expected: statusCode: 204 actual: statusCode: 201 body: { "status": "started" } complete: 1 passing, 1 failing, 0 errors, 0 skipped, 2 total complete: Tests took 18ms
46. Creating a Game
47. ### Create a game [POST /new]
48. ### Create a game [POST /new] + Response 201 (application/json)
49. ### Create a game [POST /new] + Response 201 (application/json) { "person": { "name": "Scarlet" }, "game": { "id": "abc", "players": [], "status": "unstarted" } }
50. Data Structures
51. ## Data Structures ### Person (object) + name: Scarlet
52. ## Game [/game/{id}]
53. ## Game [/game/{id}] + Attributes + id: c9d60ae4 - Unique identifier for this game
54. ## Game [/game/{id}] + Attributes + id: c9d60ae4 - Unique identifier for this game + players (array[Player]) - Players currently in the game
55. ## Game [/game/{id}] + Attributes + id: c9d60ae4 - Unique identifier for this game + players (array[Player]) - Players currently in the game + status (enum) - Current state of the game + Members + unstarted - Waiting for players to join + starting - Waiting for a player to start + running - Game in progress + ended - Game over
59. ### Create a game [POST /new] + Response 201 (application/json) + Attributes + person (Person) + game (Game)
60. JSON { "player": { "name": "Scarlet" }, "game": { "id": "c9d60ae", "players": [ { "name": "Scarlet" } ], "status": "unstarted" } }
61. JSON Schema { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "game": { "type": "object", "properties": { ... "status": { "type": "string", "enum": [ "unstarted", "starting", "running", "ended" ], "description": "Current state of the game" } } } } }
62. Joining a Game
63. ### Join a Game [POST] + Response 200 (application/json) + Attributes (Person)
64. ### Join a Game [POST] + Response 200 (application/json) + Attributes (Person) + Response 418 (application/json) + Attributes + error: You cannot join a started game
65. Getting Started • API Blueprint (apiblueprint.org) • Editors • Apiary (apiary.io) • Aglio • Dredd
68. Finding Existing Design Patterns in API Blueprint
73. Documentation
77. Integration
78. Aglio
82. Contributing to API Blueprint
83. RFC Process
86. Roadmap
87. Roadmap • Response based on parameter values • Affording Actions • MSON Parameters and Headers • Authentication • Multiple files (modularity) • External assets • State machine description
88. Response based on parameter values
89. Response based on parameter values ### Search for a question [GET /questions{?query,limit}] + Parameters + query: language - Search query + limit: 20 (number, optional) - Maximum number of questions returned + Response 200 (application/json) [ { "question": "Favourite programming language?" }, { "question": "API Description language preference" } ] + Request A search limited to one result + Parameters + query: language + limit: 1 + Response 200 (application/json) [ { "question": "Favourite programming language?" } ]
91. MSON Parameters and Headers
92. • Design First • Prototype • TDD
93. https://fuller.li/slides kyle@apiary.io Kyle Fuller