I am having an argument with a fellow developer and need some outside perspective. When defining a REST Api, what is normal to have as the input argument?
Say we have the following call GetCarByModelName, would you expect this to take one input, namely the ModelName (string, enum, what ever) or the whole Car object where ModelName is on of the fields and then the internal workings of the function would look at the ModelName and ignore all the other information if its provided?
1. GetCarByModelName(ModelName)
2. GetCarByModelName(Car)
Car
{
Type : string
Weight : int
ProductionYearStart : DateTime
ProductionYearStop : DateTime
Price : Decimal
ModelName : string
BrandName : string
}
First let's get something out of the way - HTTP GET and sending a JSON body (which seems like what you're intending to do).
The author of REST himself commented here, that:
Server semantics for GET, however, are restricted such that a body, if any, has no semantic meaning to the request. .... So, yes, you can send a body with GET, and no, it is never useful to do so.
In the question you mentioned:
where ModelName is on of the fields and then the internal workings of the function would look at the ModelName and ignore all the other information if its provided?
Generally you should not send HTTP GET with a body no matter one or many fields (so you might say you're both wrong).
GetCarByModelName obviously has the semantics of HTTP GET request. In a common REST api, someone would expect you will have a Car resource, which can be queried by the model name. But let's give it some context - a car is in a car dealer shop and the user wants to get a list of BMW model X5 cars. This should look something like:
HTTP GET /api/cardealer/{carDealerId}/cars?modelName=BMW%20X5