Designing APIs for Humans - Write the Docs 2016

Designing APIs for Humans - Write the Docs 2016

D200a17dd269fd4001bacb11662dab4b?s=128

Kyle Fuller

March 04, 2016
Tweet

Transcript

  1. 2.
  2. 3.
  3. 9.

    "The best API designs tends to be those that are

    understood by everybody involved in the API- lifecycle"
  4. 10.
  5. 12.
  6. 13.
  7. 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.
  8. 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. ...
  9. 16.
  10. 17.
  11. 18.
  12. 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.
  13. 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.
  14. 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.
  15. 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
  16. 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." } ] }
  17. 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
  18. 35.
  19. 36.
  20. 37.
  21. 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
  22. 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
  23. 49.

    ### Create a game [POST /new] + Response 201 (application/json)

    { "person": { "name": "Scarlet" }, "game": { "id": "abc", "players": [], "status": "unstarted" } }
  24. 54.

    ## Game [/game/{id}] + Attributes + id: c9d60ae4 - Unique

    identifier for this game + players (array[Player]) - Players currently in the game
  25. 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
  26. 56.
  27. 57.
  28. 58.
  29. 59.

    ### Create a game [POST /new] + Response 201 (application/json)

    + Attributes + person (Person) + game (Game)
  30. 60.

    JSON { "player": { "name": "Scarlet" }, "game": { "id":

    "c9d60ae", "players": [ { "name": "Scarlet" } ], "status": "unstarted" } }
  31. 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" } } } } }
  32. 64.

    ### Join a Game [POST] + Response 200 (application/json) +

    Attributes (Person) + Response 418 (application/json) + Attributes + error: You cannot join a started game
  33. 66.
  34. 67.
  35. 69.
  36. 70.
  37. 71.
  38. 72.
  39. 74.
  40. 75.
  41. 76.
  42. 78.
  43. 79.
  44. 80.
  45. 81.
  46. 84.
  47. 85.
  48. 86.
  49. 87.

    Roadmap • Response based on parameter values • Affording Actions

    • MSON Parameters and Headers • Authentication • Multiple files (modularity) • External assets • State machine description
  50. 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?" } ]
  51. 90.