RESTful convention to update resource by id or by type and language

Question

Currently my GET request by type and language can return only one document:

GET /documents?type=invitation&language=en

id: 50
text: "I would like to invite..."

What is a correct restful convention to update resource?

PUT /documents?type=invitation&language=en

?? Or maybe I should update resource only by id?

PUT /documents/50

Answer 1

You generally use PUT when you're updating the whole resource. Here you're just sending a subset of resource data - so you should use PATCH.

Your URL should be:

PATCH /documents/{id}

Then you have all the data you want to update in the request payload:

{
   "type": "invitation",
   "language": "en"
}

So you're now updating only one object per request and using the appropriate method and resource notation.