Documenting RESTful APIs

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: ht tp: / /creat ivecommons.org/ l icenses/by-nc/3.0/

SPRINGONE2GXWASHINGTON, DC

Documenting RESTful APIsAndy Wilkinson

@ankinson


How RESTful is your API?

2


REST maturity model

3

Hypermedia

HTTPverbs

Separate Resources

XML-RPC SOAPXML-RPC

Level 0 Level 1 Level 2 Level 3

http://www.crummy.com/writing/speaking/2008-QCon/act3.htmlhttp://martinfowler.com/articles/richardsonMaturityModel.html

http://www.crummy.com/writing/speaking/2008-QCon/act3.html

http://martinfowler.com/articles/richardsonMaturityModel.html


How RESTful do you want it to be?

4


Making your API easy to document

5


Consistency

6

HTTP status codesHTTP verbs


Uniqueness

7

Use distinct relations on your links

Unless otherwise indicated, these sl ides are © 2013-2015 Pivotal Software, Inc. and l icensed under a Creat ive Commons Attr ibut ion-NonCommercial l icense: ht tp: / /creat ivecommons.org/ l icenses/by-nc/3.0/ 8

"_links" : { "self" : { "href" : "http://localhost:8080/" }, "notes" : { "href" : "http://localhost:8080/notes" }, "tags" : { "href" : "http://localhost:8080/tags" }


"_links" : { "self" : { "href" : "http://localhost:8080/tags/3" }, "tagged-notes" : { "href" : "http://localhost:8080/tags/3/notes" }}


What should you document?

10


Cross-cutting concerns

11

HTTP status codesHTTP verbs (PUT vs PATCH)

Authentication and authorisationRate limiting

…


Resources

12

What do the represent?What input do they accept?

What output do the produce?


Links

13

Where can you go?What will you find when you get there?


What shouldn’t you document?

14


URIs

15


What does it look like whenyou get it wrong?

16

Learning from my mistakes


And when you get it right?

18


RESTful API documentation tools

20


Swagger

21

http://swagger.io

springfox/springfox

http://swagger.io


You get a lot for little effort

22


But…23


It doesn’t support hypermedia

24

https://github.com/swagger-api/swagger-core/issues/97


It’s URI centric

25


Always playing catch up – ResponseEntity

26

https://github.com/springfox/springfox/issues/532


Always playing catch up – HttpHeaders

27


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) {

…}


It isn’t dry

29


@ResponseStatus(HttpStatus.CREATED)public HttpHeaders create(@RequestBody UserInput userInput) { … }

@ExceptionHandler(IllegalArgumentException.class)private ResponseEntity<Void> handleIllegalArgumentException() {

return new ResponseEntity<>(HttpStatus.BAD_REQUEST);}


It isn’t dry

30






It isn’t dry

31






Swagger2Markup

32

Swagger2Markup/swagger2markup


HAL and HAL Browser

33

http://stateless.co/hal_specification.html

mikekelly/hal-browser

http://stateless.co/hal_specification.html


HAL Browser demo

34


Spring REST Docs

35

spring-projects/spring-restdocs

http://projects.spring.io/spring-restdocs

http://swagger.io


Write as much as possible in a format that’s designed for writing

36


Don’t use the implementation to provide the documentation

37


Provide some guarantees that the documentation is accurate

TDD – Test-Driven Documentation

38


AsciidoctorSpring MVC TestMaven or Gradle

39

spring-projects/spring-restdocs


@Testpublic 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


[source,bash]----$ curl 'http://localhost:8080/' -i----


[source,http]----HTTP/1.1 200 OKContent-Type: application/hal+json

{ "_links" : { "tags" : { "href" : "http://localhost:8080/tags" }, "notes" : { "href" : "http://localhost:8080/notes" }}


this.mockMvc.perform(get("/")) .andExpect(status().isOk()) .andDo(document("index", links( linkWithRel("notes").description( "The <<resources-notes, Notes resource>>"), linkWithRel("tags").description( "The <<resources-tags, Tags resource>>") ), responseFields( fieldWithPath("_links").description( "<<resources-index-links,Links>> to other resources") )));

4

3

2

1

5

6


Spring REST Docs demo

50


Thank you

51

@ankinson

wilkinsona

[email protected]

Documenting RESTful APIs

Technology

Transcript of Documenting RESTful APIs