Designing APIs for Humans - Write the Docs 2016

Transcript

1. Designing APIs for Humans Kyle Fuller

2. None
3. None

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"
10. None

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. ...
16. None
17. None

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

35. None
36. None
37. None

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
56. None
57. None
58. None

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
66. None
67. None

68. Finding Existing Design Patterns in API Blueprint

69. None
70. None
71. None
72. None

73. Documentation

74. None
75. None
76. None

77. Integration

78. Aglio

79. None
80. None
81. None

82. Contributing to API Blueprint

83. RFC Process

84. None
85. None

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?" } ]
90. None

91. MSON Parameters and Headers

92. • Design First • Prototype • TDD

93. https://fuller.li/slides kyle@apiary.io Kyle Fuller