Say I’m offering a REST’ish API that offers you Meals
Now If you want to get ALL meals naturally you get it through something like:
GET /meals
if you want to filter those meals you can do something like:
GET /meals?vegetarian=true
But what do I do for a very complex Request where the “query” looks more like:
[
vegetarian=true,
people = [
person1 = [age: 15, allergens: [peanut, shrimp]],
person2 = [age: 25, allergens: []],
]
]
My approach would be to send this via. a JSON-POST but if you follow the REST paradigm this would be a GET as the Underlying Resource is left untouched.
Should I stay with my POST approach which seems a bit unnatural to me or should I just pack all the information into one giant GET-Parameter string?
2
It feels you have an additional resource, a mealsAdvice or something. A resource in REST is not a database table or something. So you can just return meals table records from your database in another resource like a mealsAdvice.
That would get you to this:
POST /mealsAdvices
...your data example here here...
Returns
HTTP/1.1 201 Created
Location: /mealsAdvices/123
Optionally also contains your meals instantly so you don’t have to visit the url:
HTTP/1.1 201 Created
Location: /mealsAdvices/123
...your data example here here... (can be handy to see why that advice was made)
... meals advice here...
Alternative which may be interesting for your app: Store all advices for a user under:
/users/{userId}/mealsAdvices
Then you can also show a list of advices they had before. You could for example also “like” the advices with an update to that advice. Just depends on what you want to do with the advices later on.
2
GET should be preferred if you can stand it.
However, there is no rule that says the query has to be key value pairs.
GET /meals?%5B%0A%20%20%20%20vegetarian%3Dtrue%2C%0A%20%20%20%20persons%20%3D%20%5B%0A%20%20%20%20%20%20person1%20%3D%20%5Bage%3A%2015%2C%20allergens%3A%20%5Bpeanut%2C%20shrimp%5D%5D%2C%0A%20%20%20%20%20%20person2%20%3D%20%5Bage%3A%2025%2C%20allergens%3A%20%5B%5D%5D%2C%0A%20%20%20%20%5D%0A%5D
Nothing wrong with that identifier so long as you don’t start running into artificial limits in your user-agents/gateways.
You might also consider looking into GraphQL. The structure of a GraphQL query is a bit like an object representation, so there may be useful ideas to lift from those experimenting with combining GraphQL and “REST”.
You might also want to look into the proposal for SEARCH, and see if any new progress is being made.
The REST police might be unhappy with you about the RPC-ish nature of the query; using a free form json block (like using a graphQL query) looks very much like a bunch of information about how to create a query being communicated out of band from the server to the client. This is a no-no if you are expecting the client and the server to evolve independently of each other. In most cases, it is fine at a practical level.