And some more REST tips

In previous blog posts I have covered some ideas and tips for achieving a REST architecture. In this post, I cover a few more ideas and tips.

Caching

• Caching is a big part of the original dissertation.  See section 5.1.4 
• Strategies include validation (client checks it has the latest version) and expiration (client assumes it has the latest version until a specified time)
• Expiration:
• Expires header tells client when resource is going to expire. The value 0 means avoid caching
• Cache-Control
• Use max-age directive to specify how long response should be considered valid for; s-maxage for shared caches
• Can also be used in requests no-cache means re validate response with server
• Validation
• Etag - unique version of resource. Used in conjunction with If-none-match request header
• Last-Modified - tells client when resource last changed

Controller APIs

• When something does fit neatly to a CRUD operation, consider a Controller API

Handling Dates

• Use ISO-8601 for your dates - better for natural sorting, handles timezone, locale nuetral, support from most programming languages
• Accept any timezone as anyone in the world may call your API
• Store in UTC, not in your server's timezone.  There should be no offset when persisted.
• Return in UTC.  Allow the client to adjust to its timezone as necessary
• Don't use time if you don't need it.  If Date only suffices, only persist Date. This means, timezone complexity goes away. 

HEAD

• HEAD action should return response headers

Headers

• Always return what headers are useful.  Consider: 
• Content-Type
• Content-Length
• Last-Modified
• ETag
• Location

Hypermedia (advantages)

• Less coupling
• Consistent format for links => cleaner client code
• Developer productivity: API's easier to navigate 
• Make easier to introduce services in a more granular way
• Code easier to debug - messages always have the URL that created them via the self link

Hypermedia (choices)

• HAL - reduces Address coupling 
• SIREN - reduces Address and Actions coupling
• Collection+JSON (CJ) - reduces Address, Action and Object coupling

Idempotent

• Can be called several times and return the same result
• OPTIONS, GET, HEAD, PUT and DELETE are all idempotent

Long Running Requests

• Some operations take a long time.  In such cases, consider returning a 202 with the location field set to a URL the client can poll to check for operation progress.

Method not allowed

• If an API only supports GET, it should return a 405 for any PUT, POST, DELETEs etc

Must Ignore Principle

• Clients should ignore data they are not interested in. This makes it much easier for APIs to be backwardly compatible .  If an API returns extra data and some clients aren't expecting it they will just ignore it. 

Not acceptable

• When a resource doesn't support a specific media type, it should return 406  (see Masse, Rule: 406 (“Not Acceptable”) must be used when the requested media type cannot be served

OPTIONS

• OPTIONS should return what actions are available on a resource

Partial Update

• Handle partial updates with  PATCH

Query

• The query component of a URI should be used to filter collections

Resource Creation

• When a Resource has been successfully created a 201 should be returned 
• The location header should indicate the URL to get the Resource. 

Safe

• Actions are considered Safe if they Do not modify resources
• OPTIONS, GET and HEAD are safe

Self link

• Response bodies should always include a self link - the URL that was used to return the resource. 

Singular or Plural?

• Use Singular for Singular Document type resource  - when there can only be one.  For example: /humans/12343343/head
• Otherwise plural