Skip to main content
added 19 characters in body
Source Link
Andy
  • 10.4k
  • 4
  • 27
  • 51

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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, and. If you decided to read or update the document with such strange id, whichyou could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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, and you decided to read or update the document, which could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

added 2 characters in body
Source Link
Andy
  • 10.4k
  • 4
  • 27
  • 51

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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/attachmentsx6bFAK6/attachments, and you decided to read or update the document, which could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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, and you decided to read or update the document, which could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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, and you decided to read or update the document, which could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).

Source Link
Andy
  • 10.4k
  • 4
  • 27
  • 51

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 POST /api/docs,
  • getting a specific document should be GET /api/docs/(doc-id),
  • 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, and you decided to read or update the document, which could end up hitting the following endpoints:

  • GET /api/docs/x6bFAK6/attachments,
  • PUT /api/docs/x6bFAK6/attachments,

which any solid REST framework should refuse to process, because neither GET nor 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).