Designing a REST-ful API using Spring 3.md

What is REST?

• Representational State Transfer
• An architectural style for designing distributed systems
• Not a standard, but rather a set of constraints
  • Client/Server, Stateless, Uniform Interface, etc.
• Not tied to HTTP, but associated most commonly with it

Uniform Interface

• More flexible principals (no hard and fast rules)
  • Identification of resources
  • Manipulation of resources
  • Self-descriptive messages
  • Hypermedia as the engine of application state

HTTP's Uniform Interface

- URI's identify resources
- HTTP verbs describe a limited set of operations that can be used to manipulate a resource
	- GET
	- DELETE
	- PUT
	- POST
	- less used other verbs

• Headers help describe the messages

GET

• Retrieve information
• Must be safe and idemportent
  • Can have side effects, but since the user doesn't expect them, they shouldn't be critical to the operation of the system
• GET can be conditional or partial
  • If-Modified-Since
  • Range

DELETE

• Request that a resource be removed
• The resource doesn't have to be removed immediately
  • Removal may be a long running task

PUT

• Requests that the entity passed be stored at the URI
• Can be used to create a new entity or modify an existing one
  • Creation of new entities is uncommon as it allows the client to select the id of the new entity

POST

• Requests that the resource at a URI do something with the enclosed entity
• What that something is could be almost anything
  • Create
  • Modify
• The major difference between POST and PUT are what resource the request URI identifies

Interaction Model

• Create Game
• List the current state of all Doors
• Select a Door
• The Game will open one of the other non-Juergen Doors
• Open one of the two remaining Doors
• List the outcome of the Game
• Delete the Game

Create a Game

• Well-known entry point
• Doesn't require any input other that requesting that a game be created
• Needs to return to us a resource identifier (URI) of the newly created game

List the current state of all Doors

• Needs to return to us a collection that represents the state of all doors in the game
• Design doesn't have 'Door 1', 'Door 2', and 'Door 3', just three doors.

Select a Door

• There is no HTTP verb 'SELECT', so how do we represent the selection of a door?
• Request a resource mutation that leaves resource in desired state.

PUT /games/1/doors/2 {"status": "SELECTED"}

Open a Door

• Like Select, we want to request a mutation to the desired state
• Since the same (or same type of ) resource is being modified, we re-use the same payload

PUT /games/1/doors/3 {"status": "OPEN"}

List the final state of the Game

• Needs to return to an object hat represents the state of the game

GET /games/0 {"state": "WON"}

Destroy the Game

• No input required
• No output required

DELTE /games/0

What is HATEOAS?

• Hypermedia As The Engine Of Application State
• The client doesn't have a built in knowledge of how to navigate and manipulate the model
• Instead server provides that information dynamically to the suer
• Implemented by using media types and link relations

Media Types

• A resource can be represented in different ways
  • JSON, XML, etc.
• A client doesn't know what a server is going to send it
• A server doesn't know what a client can handle
• Content types are negotiated using headers
  • Client describes what it wants with Accept header
  • Server (and client during POST and PUT) describes what it is sending with Content-Type header

Link Relations

• A client cannot be expected to know what a resource is related to and where those relations are located
• The server describes these relations as part of its payload
• Link has two parts
  • rel
  • href
• del values are "standardised" so client can recognise them
  • <link rel="stylesheet" href="…"/>
  • {"del": "doors", "href": "…"}

Testing

• Testing of web APIs isn't easy
  • In container, end-to-end, string comparison, etc.
  • Out of container, Java objects, bypassing much of Spring's magic
• What we want is out of container, but with as much of Spring as we can get

Spring MVC Testing

• Coming in Spring 3.2
• Bootstraps most of Spring's MVC infrastructure so that you unit and integration test your web application end-to-end
• Provides APIs for testing interesting parts of requests and responses

Using the API

• Designed, implemented, and tested but can you actually use this API?
• Goals
  • Single URL
  • Link Traversal
  • Content Negotiation

Round Up

• API Design Matters
  • URIs represent resources, not actions
  • HTTP verbs are general, but can be used in ways that make anything possible
• Implementation isn't rocket science
  • Spring MVC
  • Spring HATEOAS
• Easy testing
  • Out-of-container, but full Spring stack