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
- Cache-Control
- 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
| Published on Java Code Geeks with permission by Alex Staveley, partner at our JCG program. See the original article here: And some more REST tips Opinions expressed by Java Code Geeks contributors are their own. |
