Several people have suggested that instead of having
POST /docs/findAll to list all documents the URL schema should be
GET /docs. While true, sometimes a
GET request simply does not cut it due to its length limitations. In a case where you would like to have a very complex search engine on a certain entity type, e.g. the documents, accepting nested objects,... representing searching criteria, it's completely valid to have an endpoint for searching represented using
POST HTTP method because it allows you to pass in large body (instead of passing it as a query parameter).
This problem aside, while following at least some good REST practices, you should never really encounter the issue you're worried about, that is unless you start generating identifier containing slashes (which I strongly recommend you not to do).
In your example, by following some basic REST principles:
- creating a new document should be
- getting a specific document should be
- updating a specific document should be
PUT /api/docs/(doc-id) or
PATCH /api/docs/(doc-id) (depending on the use case).
As you can see, the endpoint with the format
POST /api/docs/(something...) is still free and not conflicting with anything previously created. Therefore the mismatched resolution of endpoint you're worried about cannot happen.
In a scenario where you would e.g. allow adding attachments to documents, you would have a new endpoint, ideally looking like this:
POST /api/docs/(doc-is)/attachments, so your
POST /api/docs/findAll wouldn't be conflicting with this one either, because the schema differs. Unless, as I have mentioned, you actually allow generating identifiers with slashes in them and on the extremely rare occasion you would end up with an identifier looking for example like this:
x6bFAK6/attachments. If you decided to read or update the document with such strange id, you could end up hitting the following endpoints:
which any solid REST framework should refuse to process, because neither
PUT method is acceptable by the
POST /api/docs/(doc-id)/attachments endpoint, and a standalone
POST /api/docs/(doc-id) shouldn't exist either (as mentioned earlier in this post).