REST API Design - creating a resource by loading by ID
My REST service needs to support the ability to load / reload a resource and create it directly.
API:
GET /books
GET /books/12345
DELETE /books/12345
The book looks something like this:
{"id": 12345, "title": "three little bears", "author": ...}
It is not clear if there is
Request: PUT /books/12345
Response: HTTP 204 No Content
or
Request: POST /books
Payload: {"id": 12345}
Response: HTTP 201 Created, Location: /books/12345
is the best approach to load / reload a book.
Details: "load" / "reload" will access the database to get the book by id, and put the result in a persistent cache. The cache is what is requested for GET requests. Book attributes can change in the database, ie "load" / "reload" is not idempotent. Only the administrator will be able to use the load / reload and delete operations.
I believe the correct approach is POST because PUT should be idempotent. However, POST seems strange because multiple POST files against / book for id = 12345 will only result in a single resource being created (albeit re-created multiple times)
I've looked at additional options below, but they seem more egregious:
* POST /books/12345/load
* POST /books/load, with payload {"id": 12345}
* POST /load/book, with payload {"id": 12345}
Thoughts?
To complicate things further, I would also like to suggest an asynchronous load / reload operation, but I don't want to create an operation / job resource that the user can track down, I just want to fire and forget.
Example: For book 12345, load / reload asynchronously to cache. I need a service to respond with HTTP 202 Accepted and that's enough. There is no need to ever ask what happens to boot / reboot.
TL; DR: I am creating a REST service to store a cache of books. Load / reload and delete operations can only be performed by an administrator, whereas GET is open to everyone. The load / reload operation should load / reload the record from the database.
source to share
If you understood correctly, you have
- Origin
- Database
- clients
If the client is GET
a book
, it fetches the resource from the database. The database doesn't know if this book
one is being changed in the meantime, is it serving an outdated version? So you want the client POST
or PUT
resource to force the database to fetch the record again from the source?
Think about it:
The origin caches its content, the database caches its content, and the client caches.
If the user hits F5, the client will reload the resource, right? Is this good behavior? not. Would it be better for the client to check if the resource is out of date or not, and only when needed if needed? Yes. This can be achieved by sending HTTP-HEAD
a server request for the last modified date, if the clients lookup date is older then it needs to perform the selection again, otherwise it can serve from the cache.
The same is true for the constellation databse / origin. The database has to check its contents, is still the last to query and serve it or retrieve it from the source, update the caches and serve the new record.
This way the client will GET
resoure, to be exact, if he does not want to modify the resource in any way.
source to share
I think you shouldn't use action names in the resource path (something like /books/12345/reload
, ...), as this is not really RESTful. However, I agree with you that the method POST
is the correct method.
IMO you should use a method POST
for the resource path /books/12345
. It will correspond to loading / reloading an activity and can be asynchronous, i.e. return a 202è. If you already have a method
POST status code for that resource, you should consider using the strategy described in this blog post: https://templth.wordpress.com/2015/03 / 20 / handling-multiple-actions-for-a-post-method / .
Hope this helps you Thierry
source to share