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