I use Laravel as a REST API service for uploading and storing books. The book service follows the standard REST convention:
GET: /api/books and /api/books/<book_id> for retrieving book(s)
PUT: /api/books/<book_id> for updating a book
POST: /api/books for adding a new book
DELETE: /api/books/<book_id> for deleting a book
So far so good.
Now I need another endpoint which should be used for creating a Zip file out of a book and some images. So the book is already on the server (in a database). The images need to be uploaded temporarily by the client and are NOT saved on the server. Then the images and the books are compressed and the resulting file is returned back to the client.
So I need an endpoint like /api/books/{book_id}/compress. When calling this endpoint, the client attaches the images in the request body.
How do I express that in a RESTful way?
Should that be a GET or POST request? This endpoint does not store anything on the server, so it should be a GET request from my point of view. But if it is GET, can I add images to the request body? Because that’s actually supposed to be handled by POST requests.
Advertisement
Answer
Funny you ask. I have had the same question once before and I remember someone telling me that a GET request originally does not have a request body. However I think (so I am not sure) it was still possible. Unfortunately I am unable to find that example.
According to the w3 documentation the POST request can be used for the following:
- Annotation of existing resources;
- Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
- Providing a block of data, such as the result of submitting a form, to a data-handling process;
- Extending a database through an append operation.
I think in your case the “Providing a block of data, such as the result of submitting a form, to a data-handling process;” applies here.
Personally I am very strict in following a certain pattern in route definition and their purpose: /{resource}/{identifier?}/{relatedResource?|action?}.
In this case I would agree with /api/books/{book_id}/compress since it comlies with the listed usecases of POST.