Designing APIs for Humans - Write the Docs 2016

Transcript

1. Designing APIs for
   Humans
   Kyle Fuller
   

   View Slide

2. View Slide

3. View Slide

4. Focussed on Collaboration
   

   View Slide

5. # GET /message
   + Response 200 (text/plain)
   Hello World!
   

   View Slide

6. Think Before you Code
   

   View Slide

7. Your API
   

   View Slide

8. API Facade
   

   View Slide

9. "The best API designs tends
   to be those that are
   understood by everybody
   involved in the API-
   lifecycle"
   

   View Slide

10. View Slide

11. Designing our
    first API
    

    View Slide

12. Cluedo
    

    View Slide

13. # Cluedo
    

    View Slide

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.
    

    View Slide

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

    View Slide

16. View Slide

17. View Slide

18. ## Game
    

    View Slide

19. ## Game
    ### Begin play
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

22. ## Game [/game/{id}]
    + Parameters
    + id - Unique identifier for a game
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

25. Resource: Game
    Action: Begin play
    • Example HTTP Response
    

    View Slide

26. Human Friendly
    

    View Slide

27. Machine Readable
    

    View Slide

28. $ drafter -f json cluedo.apib
    

    View Slide

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

    View Slide

30. Prototyping
    

    View Slide

31. Mock-server
    

    View Slide

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
    

    View Slide

33. $ curl http://private-ceaf6d-cluedo.apiary-mock.com/game/c9d60ae4
    {
    "players": [
    {
    "name": "scarlet",
    "position": { "x": 12, "y": 6, "room": "ballroom" }
    }
    ],
    "status": "unstarted"
    }
    

    View Slide

34. Traffic Inspector
    

    View Slide

35. View Slide

36. View Slide

37. View Slide

38. Implementation
    

    View Slide

39. 404 "Not Found"
    

    View Slide

40. How do you test your
    API documentation?
    

    View Slide

41. You Don't.
    

    View Slide

42. Dredd
    https://github.com/apiaryio/dredd
    

    View Slide

43. $ dredd cluedo.apib https://localhost:8080
    

    View Slide

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
    

    View Slide

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
    

    View Slide

46. Creating a Game
    

    View Slide

47. ### Create a game [POST /new]
    

    View Slide

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

    View Slide

49. ### Create a game [POST /new]
    + Response 201 (application/json)
    {
    "person": {
    "name": "Scarlet"
    },
    "game": {
    "id": "abc",
    "players": [],
    "status": "unstarted"
    }
    }
    

    View Slide

50. Data Structures
    

    View Slide

51. ## Data Structures
    ### Person (object)
    + name: Scarlet
    

    View Slide

52. ## Game [/game/{id}]
    

    View Slide

53. ## Game [/game/{id}]
    + Attributes
    + id: c9d60ae4 - Unique identifier for this game
    

    View Slide

54. ## Game [/game/{id}]
    + Attributes
    + id: c9d60ae4 - Unique identifier for this game
    + players (array[Player]) - Players currently in the game
    

    View Slide

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
    

    View Slide

56. View Slide

57. View Slide

58. View Slide

59. ### Create a game [POST /new]
    + Response 201 (application/json)
    + Attributes
    + person (Person)
    + game (Game)
    

    View Slide

60. JSON
    {
    "player": {
    "name": "Scarlet"
    },
    "game": {
    "id": "c9d60ae",
    "players": [
    {
    "name": "Scarlet"
    }
    ],
    "status": "unstarted"
    }
    }
    

    View Slide

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"
    }
    }
    }
    }
    }
    

    View Slide

62. Joining a Game
    

    View Slide

63. ### Join a Game [POST]
    + Response 200 (application/json)
    + Attributes (Person)
    

    View Slide

64. ### Join a Game [POST]
    + Response 200 (application/json)
    + Attributes (Person)
    + Response 418 (application/json)
    + Attributes
    + error: You cannot join a started game
    

    View Slide

65. Getting Started
    • API Blueprint (apiblueprint.org)
    • Editors
    • Apiary (apiary.io)
    • Aglio
    • Dredd
    

    View Slide

66. View Slide

67. View Slide

68. Finding Existing Design
    Patterns in API Blueprint
    

    View Slide

69. View Slide

70. View Slide

71. View Slide

72. View Slide

73. Documentation
    

    View Slide

74. View Slide

75. View Slide

76. View Slide

77. Integration
    

    View Slide

78. Aglio
    

    View Slide

79. View Slide

80. View Slide

81. View Slide

82. Contributing to
    API Blueprint
    

    View Slide

83. RFC Process
    

    View Slide

84. View Slide

85. View Slide

86. Roadmap
    

    View Slide

87. Roadmap
    • Response based on parameter values
    • Affording Actions
    • MSON Parameters and Headers
    • Authentication
    • Multiple files (modularity)
    • External assets
    • State machine description
    

    View Slide

88. Response based on parameter
    values
    

    View Slide

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

    View Slide

90. View Slide

91. MSON Parameters
    and Headers
    

    View Slide

92. • Design First
    • Prototype
    • TDD
    

    View Slide

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

    View Slide