I'm in the process of making an API more RESTful. At the moment I have an endpoint like this:
/booking?bookingid=123
I have updated the endpoint to be more RESTful like this:
/bookings/123
A booking looks a bit like this:
{
"bookingId":123,
"people":[
{
"personId":0,
"name":{
"forename":"Jon",
"surname":"Smith"
}
},
{
"personId":1,
"name":{
"forename":"Sarah",
"surname":"Jones"
}
}
]
}
I want to only return a booking if the booking contains a particular surname and to return Not Found if the surname doesn't exist on the booking.
The way I am looking to implement this is by adding a query string:
/bookings/123?surname="Jones"
This would return the booking above as Sarah's surname is "Jones" the booking would also be returned with a query string surname with value "Smith".
The first problem I have with this is that if a property of surname were added to the booking object it looks like the query is against that and the other problem I have is that it's querying against a single entity and not a list, is this a RESTful approach and if not then what is a better approach?
There is no definition of “RESTful” that the community agrees upon.
The closest thing to the definition of “RESTful” is Architectural Styles and the Design of Network-based Software Architectures by Roy T. Fielding, the dissertation that introduced the term “REST”. This dissertation has not a single word on how “RESTful” URLs should be structured. Instead, the idea is that the server chooses whichever URLs are convenient for it, then explicitly communicates them to the client in hypermedia links. In this kind of “RESTful” system, /booking?bookingid=123 is a perfectly good URL, as is /_content/AcmeWebApi.dll?ENDPOINT=booking&ID=123&tc=y.
However, after this dissertation (and the term “REST” with it) achieved widespread recognition, the community quickly drifted away from this idea of “REST” to a range of other, conflicting ideas of what is or is not “REST”, to the great dismay of Roy T. Fielding.
Therefore, your question cannot be usefully answered.
Consider if “RESTfulness” is really the property you’re trying to optimize for, or if you’re after some other properties, which could be, for example:
and each of which might call for a different URL design.