One really useful book about REST API design is 'The REST API Design Rulebook' by and published by O'Reilly.
One of my favourite bits was in Chapter 2 about resource archetypes.
Document
A Document is a THING (for want of a better description).
Collection
A collection is a server-managed collection of resources. The client can propose additions to the collection.
From the above examples, collections would be:
Store
A store is a client-managed collection of resources.
For example to store my favourite female names (my user name = polyglotpiglet):
Controller
A controller resource is like an executable function with inputs and outputs. It is used in REST APIs when you want to do something that doesn't fall naturally into the CRUD operations.
For example:
(weird example but hopefully it makes sense).
In this book I thought that the description of controller resources was awesome - it seems to be a common misconception that REST APIs are only appropriate for designing CRUD systems and if you want to do anything complicated it's not possible with REST. This is not my experience.
Other notes from the book
Some really useful tips about headers (making sure you set the appropriate headers and why it might be useful eg cache control, last modified time, content types etc)
No comments:
Post a Comment