Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documenting RESTful APIs

Andy Wilkinson
September 15, 2015

Documenting RESTful APIs

Slides of the talk on documenting RESTful APIs that I gave at SpringOne 2GX 2015

Andy Wilkinson

September 15, 2015
Tweet

More Decks by Andy Wilkinson

Other Decks in Programming

Transcript

  1. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    SPRINGONE2GX
    WASHINGTON, DC
    Documenting RESTful APIs
    Andy Wilkinson
    @ankinson

    View full-size slide

  2. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    How RESTful is your API?
    2

    View full-size slide

  3. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    REST maturity model
    3
    Hyper

    media
    HTTP

    verbs
    Separate
    Resources
    XML-RPC
    SOAP
    RPC
    Level 0 Level 1 Level 2 Level 3
    http://www.crummy.com/writing/speaking/2008-QCon/act3.html
    http://martinfowler.com/articles/richardsonMaturityModel.html

    View full-size slide

  4. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    How RESTful do you want it to be?
    4

    View full-size slide

  5. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Making your API easy to document
    5

    View full-size slide

  6. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Consistency
    6
    HTTP status codes
    HTTP verbs

    View full-size slide

  7. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Uniqueness
    7
    Use distinct relations on your links

    View full-size slide

  8. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    8
    "_links" : {
    "self" : {
    "href" : "http://localhost:8080/"
    },
    "notes" : {
    "href" : "http://localhost:8080/notes"
    },
    "tags" : {
    "href" : "http://localhost:8080/tags"
    }

    View full-size slide

  9. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    9
    "_links" : {
    "self" : {
    "href" : "http://localhost:8080/tags/3"
    },
    "tagged-notes" : {
    "href" : "http://localhost:8080/tags/3/notes"
    }
    }

    View full-size slide

  10. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    What should you document?
    10

    View full-size slide

  11. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Cross-cutting concerns
    11
    HTTP status codes
    HTTP verbs (PUT vs PATCH)
    Authentication and authorisation
    Rate limiting

    View full-size slide

  12. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Resources
    12
    What do the represent?
    What input do they accept?
    What output do the produce?

    View full-size slide

  13. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Links
    13
    Where can you go?
    What will you find when you get there?

    View full-size slide

  14. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    What shouldn’t you document?
    14

    View full-size slide

  15. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    URIs
    15

    View full-size slide

  16. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    What does it look like when
    you get it wrong?
    16
    Learning from my mistakes

    View full-size slide

  17. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    17

    View full-size slide

  18. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    And when you get it right?
    18

    View full-size slide

  19. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    19

    View full-size slide

  20. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    RESTful API documentation tools
    20

    View full-size slide

  21. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Swagger
    21
    http://swagger.io
    springfox/springfox

    View full-size slide

  22. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    You get a lot for little effort
    22

    View full-size slide

  23. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    But…
    23

    View full-size slide

  24. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    It doesn’t support hypermedia
    24
    https://github.com/swagger-api/swagger-core/issues/97

    View full-size slide

  25. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    It’s URI centric
    25

    View full-size slide

  26. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Always playing catch up – ResponseEntity
    26
    https://github.com/springfox/springfox/issues/532

    View full-size slide

  27. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Always playing catch up – HttpHeaders
    27

    View full-size slide

  28. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    The writing experience is unpleasant
    28
    @RequestMapping(method=RequestMethod.POST,
    consumes=MediaType.APPLICATION_JSON_VALUE)
    @ApiOperation(value = "Create a new user", notes = "The name " +
    "of the user must be at least four characters in length.")
    @ApiResponses({
    @ApiResponse(code=400, message="Bad request"),
    @ApiResponse(code=201, message="User created")})
    @ResponseStatus(HttpStatus.CREATED)
    public HttpHeaders create(@RequestBody UserInput userInput) {

    }

    View full-size slide

  29. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    It isn’t dry
    29
    @ApiResponses({
    @ApiResponse(code=400, message="Bad request"),
    @ApiResponse(code=201, message="User created")})
    @ResponseStatus(HttpStatus.CREATED)
    public HttpHeaders create(@RequestBody UserInput userInput) { … }
    @ExceptionHandler(IllegalArgumentException.class)
    private ResponseEntity handleIllegalArgumentException() {
    return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
    }

    View full-size slide

  30. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    It isn’t dry
    30
    @ApiResponses({
    @ApiResponse(code=400, message="Bad request"),
    @ApiResponse(code=201, message="User created")})
    @ResponseStatus(HttpStatus.CREATED)
    public HttpHeaders create(@RequestBody UserInput userInput) { … }
    @ExceptionHandler(IllegalArgumentException.class)
    private ResponseEntity handleIllegalArgumentException() {
    return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
    }

    View full-size slide

  31. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    It isn’t dry
    31
    @ApiResponses({
    @ApiResponse(code=400, message="Bad request"),
    @ApiResponse(code=201, message="User created")})
    @ResponseStatus(HttpStatus.CREATED)
    public HttpHeaders create(@RequestBody UserInput userInput) { … }
    @ExceptionHandler(IllegalArgumentException.class)
    private ResponseEntity handleIllegalArgumentException() {
    return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
    }

    View full-size slide

  32. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Swagger2Markup
    32
    Swagger2Markup/swagger2markup

    View full-size slide

  33. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    HAL and HAL Browser
    33
    http://stateless.co/hal_specification.html
    mikekelly/hal-browser

    View full-size slide

  34. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    HAL Browser demo
    34

    View full-size slide

  35. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Spring REST Docs
    35
    spring-projects/spring-restdocs
    http://projects.spring.io/spring-restdocs

    View full-size slide

  36. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Write as much as possible in a format that’s
    designed for writing
    36

    View full-size slide

  37. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Don’t use the implementation to provide the
    documentation
    37

    View full-size slide

  38. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Provide some guarantees that the
    documentation is accurate
    TDD – Test-Driven Documentation
    38

    View full-size slide

  39. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Asciidoctor
    Spring MVC Test
    Maven or Gradle
    39
    spring-projects/spring-restdocs

    View full-size slide

  40. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    40
    @Test
    public void index() throws Exception {
    this.mockMvc.perform(get("/"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("_links.notes",
    is(notNullValue())))
    .andExpect(jsonPath("_links.tags",
    is(notNullValue())))
    .andDo(document("index"));
    }
    5
    4
    3
    2
    1

    View full-size slide

  41. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    41
    [source,bash]
    ----
    $ curl 'http://localhost:8080/' -i
    ----

    View full-size slide

  42. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    42

    View full-size slide

  43. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    43
    [source,http]
    ----
    HTTP/1.1 200 OK
    Content-Type: application/hal+json
    {
    "_links" : {
    "tags" : {
    "href" : "http://localhost:8080/tags"
    },
    "notes" : {
    "href" : "http://localhost:8080/notes"
    }
    }

    View full-size slide

  44. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    44

    View full-size slide

  45. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    45
    this.mockMvc.perform(get("/"))
    .andExpect(status().isOk())
    .andDo(document("index",
    links(
    linkWithRel("notes").description(
    "The <>"),
    linkWithRel("tags").description(
    "The <>")
    ),
    responseFields(
    fieldWithPath("_links").description(
    "<> to other resources")
    )
    ));
    4
    3
    2
    1
    5
    6

    View full-size slide

  46. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    46
    |===
    | Relation | Description
    | notes
    | The <>
    | tags
    | The <>
    |===

    View full-size slide

  47. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    47

    View full-size slide

  48. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    48
    |===
    |Path|Type|Description
    |_links
    |Object
    |<> to other resources
    |===

    View full-size slide

  49. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    49

    View full-size slide

  50. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Spring REST Docs demo
    50

    View full-size slide

  51. Unless otherwise indicated, these slides are © 2013-2015 Pivotal Software, Inc. and licensed under a

    Creative Commons Attribution-NonCommercial license: http://creativecommons.org/licenses/by-nc/3.0/
    Thank you
    51
    @ankinson
    wilkinsona
    [email protected]

    View full-size slide