0

I've seen some questions like this, but they're from a few years ago, and I wanted to know if there's a better standard for this these days.

Let's say my API looks like this:

/api/people ?age=21 &name=\w* &country=Something &state=Someplace &city=Somewhere &language=English &includeRelatives=True|False &includePersonalDetails=True|False &includePersonalPreferences=True|False &includeTravelDetails=True|False &includeOtherStuff=True|False

And so on. This just doesn't look nice to me.

Others have recommended this approach (for the "include*" parameters)

&includes=relatives,personaldetails,personalpreferences,traveldetails,otherstuff

So clients can opt-in to what they want to include in one parameter.

With all of this said, assuming the list of query parameters is actually longer than this, what is a good pattern/practice for a proper RESTful API?

Improve this question
2
  • I think that there is no "standard". I would approach this case by case. For example, I would do /api/language/en-us/people, and /api/country/uk/people, etc. well, true, this might not be as flexible as your query string approach, but do you need this flexibility? Commented Sep 7, 2013 at 3:40
  • That is a good idea, but unfortunately I'm looking to keep one resource (ie: people), and query based off of that. Also "people" is just an example and not my actual use case, but with the right pattern it can apply to anything I assume. Commented Sep 7, 2013 at 14:45

2 Answers 2

Reset to default
2

One common approach is to POST to your people collection, with your data in a defined Json or xml structure in the http body. Your api would then return 201 created along with the unique is of the person record.

Updates would then be posted (or maybe patch) to that resource specifically. PUT could be used to fully replace the record.

Eg. POST /people to create a new resource POST/PATCH /people/123 to update PUT /people/123 to replace all of the data with new content.

I don't think there is a gloglobally accepted standard for rest, but there are sone generally accepted common approaches, and lots of opinions! :-)

Kev.

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Re-reading your question, I think you might be looking for how to do a search/filter with many parameters? For this you could post to a search resource and return a link to the results resource. Of course you could just respond with the results but some would say that's less restful.
Please never use POST if you don't change data. One of the advantages of REST is to make explicit that GET methods are "safe" (and for example to cache their result).
But POST is for sending data to a resource which can then create a new resource, which in this case would be the results resource. So I believe the use of post here is correct. The downside to this is that a client would have to make a second (get) request to retrieve the results. It also makes the backend more complex which is why some would just take a pragmatic approach and simply return the results. I agree that doing so is not restful in any pure sense.
@YorkshireKev, correct - I'm using this for searching/filtering, not creation. I've seen the POST vs GET debate on obtaining search results over and over again, and unfortunately we have the same debate with my colleagues... so this won't be acceptable for my team. I appreciate the idea though - still looking for a good pattern on using GET here instead.
One alternative instead of passing in lots of query parameters is to have a set of pre-defined views and select one of those via a single query parameter. e.g. ?view=summary ?view=all ?view=somethingelse. This would be similar to how database views can be used so simplify select statements. Of course how useful this approach would be will depend on how many different query combinations your api needs to support. I've used this approach to good effect in the past where I use a view plus a small number of additional 'filter' query parameters.
0

You could have shorter URIs by using defined vs undefined instead of True vs False.

For example:

http://acme.org/people?includePersonalDetails&includeOtherStuff

instead of

http://acme.org/people?includeRelatives=False&includePersonalDetails=True&includePersonalPreferences=False&includeTravelDetails=False&includeOtherStuff=True

URIs would be (nearly) as long as yours only when you set all boolean options to true.

Improve this answer

1 Comment

Yeah, that's along the lines of my example: &includes=relatives,personaldetails,personalpreferences,traveldetails,otherstuff, which I prefer more tbh.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.