Document POST/PUT is backwards

[remram44]

Describe the bug
POST is used for "Add or replace documents" and PUT is used for "Add or update documents" (see your documentation; I have confirmed that this is how MeiliSearch works in practice).

PUT is specifically intended for replacing. Reference: RFC 7231, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", section 4.3.4

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent in a 200 (OK) response.

POST mentions "appending data to a resource's existing representation(s)" as one of its functions.

So it appears to be exactly backwards.

To Reproduce
Insert or replace documents.

Expected behavior
If HTTP verbs are used, and they match the behavior you want, the verbs are used as intended.

MeiliSearch version: 0.23.1

[curquiza]

Hello @remram44, thanks for your feedback, I moved your issue into the right place for feedback and feature requests. Your feedback might interest our product team :)

[remram44]

In the RFC, PUT requires that the entire resource has to be represented in the payload. However, as it is, the resource being manipulated is all the documents in an index and it doesn't make sense for user experience to ask to return all the documents in the index at each operation for usage and performance reasons.

You are specifying the ID in the body rather than the URL, but other than that you match the situation perfectly. You don't have to be REST compliant, but there has to be a middle ground between 100% RESTful and using the verbs exactly backwards. This is very error-prone for anyone who has used HTTP correctly before.

I can't understand what you're saying about "returning all the documents in the index", or about making API calls for each documents.

[gmourier]

It's not clear what I meant about "returning all documents", what I meant was, if the user needs to update multiple documents in one go without specifying the id of each document, he has to send all the documents of his indexes in the same payload and in this case, the engine takes care of deleting the documents and re-indexes everything.

The other solution is to do the updates one by one on an endpoint of this type indexes/:indexUid/documents/:documentId. Let's imagine that a user wants to update 500 documents at once. He has to make 500 HTTP calls.

What other solution would allow to update some documents in one HTTP call without having the id of the concerned documents in the payload?

I can see some improvements that could be done like giving the possibility to change the name of a field for all documents that have it with a specific endpoint but that is not what we are talking about here if we are talking about updating multiple documents that can have a non-identical type of payload. e.g. (Adding a field for one document, changing the value of a different field for another document, etc..)

Can you elaborate with some examples to understand a bit more what you are asking here? It would be super appreciated and maybe clearer for us to understand each other! Thanks in advance 😇

[remram44]

I am not trying to change your API, just to get you to use the correct verbs. I never suggested that you remove IDs from the payload.

[gmourier]

Oh, I didn't get it! Which HTTP verb should we use?

[remram44]

PUT to replace, POST to update. The exact opposite of what you do. As per RFC 7231:

The PUT method requests that the state of the target resource be created or replaced (...)

POST is used for the following functions: (...) Appending data to a resource's existing representation(s)

You:

Add or replace documents: POST

Add or update documents: PUT