Search code examples
restapimicroservices

Should API PUT endpoint receive all parameters, even if they are not editable?


There is a object of a name Car in the backend database. It contains several fields:

id
name
age
vinNumber
retailerId

There is also a API that elevates adding and editing the car:

POST /car - creates a car
PUT /car/{carId} - updates a car

User of a API can provide name, age and vinNumber while creating a car in a POST body.

When updating a car user can edit name and age. VinNumber is not enabled to be edited after creating a car.

Also retailerId is not editable since it comes from another system to the backend database.

Since that said, we have two fields that should not be edited with the API: vinNumber and retailerId.

So, taking into account REST idempotency, should the PUT request require the user of the API vinNumber and retailerId to be provided also, that were received earlier by GET request? In spite these parameters should not be editable?


Solution

  • An important thing to recognize -- the HTTP specification describes the semantics of an HTTP request; what does this message mean? It allows clients and servers implemented by different organizations to collaborate without requiring a direct partnership between the two.

    The point being that a generic client can prepare a request for a generic server without needing out of band information.

    PUT, semantically, is a request that the server change its current representation of a resource to match the client's local copy.

    If "the server" was just an anemic data store (a facade in front of a file system, or a document database), then the effect of PUT at the server would just be to write the message-body as is into storage.

    The point of REST, and the uniform interface, is that your server should always understand the messages the same way that the anemic facade understands them.

    Similarly, your server should use the same shared semantics for its responses.

    If the representations you are working with include vinNumber and retailId, then the client should be sending those fields unless the request is to remove them from the representation altogether (which may or may not be allowed, depending on whether or not they are required).

    The server should understand that the request missing those fields is trying to remove them, and a request with new values in those fields is trying to change them. It can then decide what it wants to do with that request, and send the corresponding response.

    Roy Fielding wrote about GET semantics in 2002:

    HTTP does not attempt to require the results of a GET to be safe. What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property (money, BTW, is considered property for the sake of this definition).

    The same idea holds for PUT (and also the other HTTP methods); we hold the implementation responsible for loss of property if its handling of the request doesn't match the semantics.