Documenting RESTful APIs

Andy Wilkinson, Pivotal

@ankinson

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

How RESTful is your API?

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

REST maturity model

RPC

XML-RPC
SOAP

Separate
Resources

Level 0

Level 1

HTTP
verbs
Level 2

Hyper
media
Level 3

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

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

How RESTful do you

want it to be?

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Making your API

easy to document

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Consistency
HTTP status codes
HTTP verbs

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Uniqueness
Use distinct relations on your links

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

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

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

What should you document?

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Resources
What do they represent?
What input do they accept?
What output do they produce?

10

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

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

11

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Cross-cutting concerns
HTTP status codes
HTTP verbs (PUT vs PATCH)
Authentication and authorisation
Rate limiting

12

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

What shouldnt you

document?

13

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

URIs

14

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

What does it look when

you get it wrong?
!

Learning from my mistakes

15

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

16

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

And when you get it right?

17

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

18

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

RESTful API
documentation tools

19

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Swagger
http://swagger.io
martypitt/swagger-springmvc
20

20

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

It doesnt support hypermedia

21

21

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Its URI-centric

22

22

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Its leaky

23

23

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Its huge

Hibernate

!
Swagger
!

25MB

31MB

Spring Boot
Tomcat

24

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

HAL and HAL Browser

http://stateless.co/hal_specification.html
!

mikekelly/hal-browser
25

25

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

A new alternative
wilkinsona/spring-restdocs

26

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Write as much as
possible in a format thats
designed for writing

27

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Dont use the

implementation to provide
the documentation

28

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Provide some guarantees

that the documentation
is accurate

29

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Asciidoctor
Spring MVC Test
Maven or Gradle
wilkinsona/spring-restdocs

30

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

@Test
public void indexExample() throws Exception {
1 this.mockMvc.perform(get("/"))
2 .andExpect(status().isOk()))
.andExpect(jsonPath("_links.notes",
3
is(notNullValue())))
4 .andExpect(jsonPath("_links.tags",
is(notNullValue())))
5 .andDo(document("index-example"));
}

31

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

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

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

33

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

@Test
public void indexExample() throws Exception {
this.mockMvc.perform(get("/"))
1
.andExpect(status().isOk())
2 .andDo(document("index-example").withLinks(
linkWithRel("notes").description(
3 "The <<resources-notes,Notes resource>>"),
linkWithRel("tags").description(
4
"The <<resources-tags,Tags resource>>")));
}

34

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

|===
| Relation | Description

!
| notes
| The <<resources-notes,Notes resource>>

!
| tags
| The <<resources-tags,Tags resource>>
|===

35

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

36

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Please try it out

Id love your feedback
wilkinsona/spring-restdocs
37

37

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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

Thank you
@ankinson
wilkinsona
awilkinson@pivotal.io

38

38

Unless otherwise indicated, these slides are 2013-2015Pivotal Software, Inc. and licensedunder a

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