This document provides an overview of REST and best practices for REST API design. It discusses the core principles of REST, Richardson Maturity Model for REST API design, and examples demonstrating the different levels. It also covers Java support for REST APIs using JAX-RS and Spring frameworks. The document recommends practices like using plural nouns for resources and HTTP status codes for errors. It provides contact information for the author, Gábor Török, an experienced Solutions Architect.

1. GET
Gábor Török @ EPAM/Szeged

2.  Introduction, overview
 Best practices
 Java support

4.  Roy T Fielding, PhD dissertation, 2000
 Main characteristics
◦ Client-server
◦ Stateless
◦ Caching
◦ Layered architecture
◦ Code on demand
◦ URIs

5. Richardson’s Maturity Model
Image courtesy of
Martin Fowler

6.  Plain Old XML (over HTTP)
 One URI, one method

7. POST /appointmentService HTTP/1.1
<openSlotRequest date="2010-01-04"
doctor="mjones"/>

8. Level 0: POX response
HTTP/1.1 200 OK
<openSlotList>
<slot start="1400" end="1450">
<doctor id="mjones"/>
</slot>
<slot start="1600" end="1650">
<doctor id="mjones"/>
</slot>
</openSlotList>

9. POST /appointmentService HTTP/1.1
<appointmentRequest>
<slot doctor="mjones" start="1400"
end="1450"/>
<patient id="jsmith"/>
</appointmentRequest>

10. Level 0: POX response
HTTP/1.1 200 OK
<appointment>
<slot doctor="mjones" start="1400"
end="1450"/>
<patient id="jsmith"/>
</appointment>

11. Many URIs, one method

12. POST /doctors/mjones HTTP/1.1
<openSlotRequest date="2010-01-04"/>

13. Level 1: Resources response
HTTP/1.1 200 OK
<openSlotList>
<slot id="1234" doctor="mjones"
start="1400" end="1450"/>
<slot id="5678" doctor="mjones"
start="1600" end="1650"/>
</openSlotList>

14. POST /slots/1234 HTTP/1.1
<appointmentRequest>
<patient id="jsmith"/>
</appointmentRequest>

15. Level 1: Resources response
HTTP/1.1 200 OK
<appointment id="2468">
<slot id="1234" doctor="mjones"
start="1400" end="1450”/>
<patient id="jsmith"/>
</appointment>

16.  Many URIs, many (HTTP) methods
 This is what most call REST
 Best practices follow

17. GET
/doctors/mjones/slots?date=20100104&s
tatus=open HTTP/1.1

18. Level 2: Verbs response
HTTP/1.1 200 OK
<openSlotList>
<slot id="1234" doctor="mjones"
start="1400" end="1450"/>
<slot id="5678" doctor="mjones"
start="1600" end="1650"/>
</openSlotList>

19. POST /slots/1234 HTTP/1.1
<appointmentRequest>
<patient id="jsmith"/>
</appointmentRequest>

20. Level 2: Verbs response
HTTP/1.1 200 OK
<appointment id="2468">
<slot id="1234" doctor="mjones"
start="1400" end="1450”/>
<patient id="jsmith"/>
</appointment>

21. W3: „Cool URIs don’t change”
vs
Roy Fielding: „A REST API must not define fixed
resource names or hierarchies”
 HATEOAS & self-descriptive messages
 Problems: people’s awareness, tools

22. Level 3: Hypermedia response
HTTP/1.1 200 OK
<openSlotList>
<slot id="1234" doctor="mjones”
start="1400" end="1450">
<link rel="/linkrels/slot/book"
uri="/slots/1234"/>
</slot>
…
</openSlotList>

23. Level 3: Hypermedia response
HTTP/1.1 201 Created
Location: http://.../slots/1234/appointment
<appointment>
<slot id="1234" …/>
<patient id="jsmith"/>
<link rel="/linkrels/appointment/cancel"
uri="/slots/1234/appointment"/>
<link rel="self"
uri="/slots/1234/appointment"/>
</appointment>

24. Solves interop problems WSDL contract
Strong typing
Client- and server
bindings
Operations (i.e. verbs)
WS-* support (Security, GETing/POSTing an XML
AtomicTransaction, etc.)
Many proxies block PUT Non-intuitive
Level 0

26.  Resources vs actions
getTickets vs /tickets
getMusemTickets vs /tickets?type=museum

27. Plural + ID
CRUD-style operations
Concrete not abstract names
Resource GET POST PUT DELETE
/tickets List tickets Create a Bulk update Delete all
new ticket tickets
/tickets/123 Get the Error Update a Delete a
details of given ticket given ticket
one ticket

28.  http://api.company.com/cafe/v1
 Major rev only
 Numbers, not nicknames, dates, etc.

29.  HTTP status codes
200
403
500
503 204 200 400
201 400
500
404 405
401
 Short description
 Pointer to more information

30. HTTP Status Code: 401
{ "status" : "401",
"message":"Authenticate",
"code": 12345,
"more info":
http://developers.company.com/docs/er
rors/12345 }

31.  Ways to differentiate:
/tickets/123.json
/tickets/123?format=json
Accept: application/json
 Bonus: application/company.v1+json

32.  Pagination:
/tickets?offset=50&limit=25
 Partial response:
/tickets?fields=date,location
 Use defaults (documentation!)

33.  Session management – REST is stateless
 Caching – it’s very much encouraged!
 What if nouns are not appropriate – use verbs

34.  Security – preferred is OAuth, lot of
Basic/Digest over HTTPS in practice
 Subdomains:
◦ api
◦ developers for SDK
 Clean REST

36.  JSR 311: Java API for RESTful Web Services
 Annotation-driven
@GET, @Path, @PathParam, @Consumes
 Implementations
Jersey, Restlet, RESTeasy, Apache CXF
 Jax-rs-hateoas

37. jax-rs example.java

38.  Spring MVC application essentially
 Annotation-driven + XML configuration
@RequestMapping et al. + view
resolvers, message converters, et al.
 spring-hateoas

39. spring mvc example.java

40.  CRUD for JPA-entities using REST semantics
 @RestResource
 Pagination and sorting support
 spring-hateoas

41. spring data rest.java

43.  Roy Fielding’s dissertation
 REST in Practice from O’Reilly
 Apigee blog & video tutorials
 Articles, forums

44.  Levels of REST – REST ≠ CRUD
 Consistent view of best practices
 Java support

45.  Has been in the industry since late ’90s
 Has been @EPAM since 2009, acted as a Dev
Lead/PM, now Solutions Architect
 Has mobile + enterprise background
gabor.i.torok@gmail.com