587

I'm currently designing and implementing a RESTful API in PHP. However, I have been unsuccessful implementing my initial design.

GET /users # list of users GET /user/1 # get user with id 1 POST /user # create new user PUT /user/1 # modify user with id 1 DELETE /user/1 # delete user with id 1

So far pretty standard, right?

My problem is with the first one GET /users. I was considering sending parameters in the request body to filter the list. This is because I want to be able to specify complex filters without getting a super long url, like:

GET /users?parameter1=value1&parameter2=value2&parameter3=value3&parameter4=value4

Instead I wanted to have something like:

GET /users # Request body: { "parameter1": "value1", "parameter2": "value2", "parameter3": "value3", "parameter4": "value4" }

which is much more readable and gives you great possibilities to set complex filters.

Anyway, file_get_contents('php://input') didn't return the request body for GET requests. I also tried http_get_request_body(), but the shared hosting that I'm using doesn't have pecl_http. Not sure it would have helped anyway.

I found this question and realized that GET probably isn't supposed to have a request body. It was a bit inconclusive, but they advised against it.

So now I'm not sure what to do. How do you design a RESTful search/filtering function?

I suppose I could use POST, but that doesn't seem very RESTful.

Improve this question
5
  • 8
    possible duplicate of RESTful URL design for search Commented Mar 2, 2012 at 11:03
  • 96
    Be careful!!! GET method must be IDEMPOTENT, and must be "cacheable". If you send information in the body How can the system cache your request? HTTP allows caching GET request using only the URL, not the request body. For instance, this two requests: example.com { test:"some" } example.com { anotherTest:"some2" } are considered the same by the cache system: Both of them have exactly the same URL Commented Feb 23, 2015 at 11:45
  • 26
    Just to add, you should POST to the /users (collection) and not /user (single user). Commented Jun 24, 2015 at 11:34
  • 2
    Another point to consider is most app servers have access logs that logs the url and so might be anything in between. So there might be some un-intended info leak on GET. Commented Sep 24, 2018 at 15:08
  • Related: stackoverflow.com/questions/9234363/… This is a useful resource (pun unintended): rfc-editor.org/rfc/rfc7231#section-4.2.2 Commented Feb 14, 2024 at 4:38

7 Answers 7

Reset to default
474

The best way to implement a RESTful search is to consider the search itself to be a resource. Then you can use the POST verb because you are creating a search. You do not have to literally create something in a database in order to use a POST.

For example:

Accept: application/json Content-Type: application/json POST http://example.com/people/searches { "terms": { "ssn": "123456789" }, "order": { ... }, ... }

You are creating a search from the user's standpoint. The implementation details of this are irrelevant. Some RESTful APIs may not even need persistence. That is an implementation detail.

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

36 Comments

One significant limitation to using a POST request for a search endpoint is that it cannot be bookmarked. Bookmarking search results (particularly complex queries) can be quite useful.
Searches, by their nature, are transient: data evolves between two searches with the same parameters, so I think that a GET request does not map cleanly to the search pattern. Instead, the search request should be POST (/Resource/search), then you can save that search and redirect to a search result, e.g. /Resource/search/iyn3zrt. That way, GET requests succeed and make sense.
I don't think post is suitable method for searching, data for normal GET requests could vary over time too.
Might as well just dump all verbs, and use POST for everything... But seriously, if we were to extrapolate this logic, then all dynamic pages should be retrieved using POST instead of GET, because we're creating a new (and potentially unique) HTML / JSON / whatever document with every request. Can't believe this answer has so many upvotes.
This is absolutely the worst possible answer. I can't believe it has so many upvotes. This answer explains why: programmers.stackexchange.com/questions/233164/…
|
218

If you use the request body in a GET request, you're breaking the REST principle, because your GET request won't be able to be cached, because cache system uses only the URL.

What's worse, your URL can't be bookmarked, because the URL doesn't contain all the information needed to redirect the user to this page.

Use URL or Query parameters instead of request body parameters, e.g.:

/myapp?var1=xxxx&var2=xxxx /myapp;var1=xxxx/resource;var2=xxxx

In fact, the HTTP RFC 7231 says that:

A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.

For more information take a look here.

Improve this answer

6 Comments

Learn from my mistake - I designed an api using the accepted answer's suggestion (POSTing json), but am moving over to url parameters. Bookmark-ability may be more important than you think. In my case, there was a need to direct traffic to certain search queries (ad campaign). Also, using the history API makes more sense with URL parameters.
It depends on how its used. If you are linking to a URL that loads the page based on those parameters, it make sense, but if the main page is doing an AJAX call only to get the data based on filter parameters, you can't bookmark that anyway because its an ajax call and has no bearing. Naturally, you could also bookmark a URL that when you go there builds up a filter and POSTs that to the ajax call and it would work just fine.
@DanielLorenz For the best user experience, the URL should still be changed through the History API in that case. I can't stand when a website doesn't allow using the browser back functionality to navigate to previous pages. And if it is a standard server side generated page the only way to make it bookmarkable would to use a GET request. It seems that good ol' query parameters are the best solution.
@Nathan I think I misread this answer. I was talking about using query string parameters in a get. You should never use body parameters in a GET call because that would be completely useless. I was talking more about a GET with query string could be used/bookmarked and then at startup of the page, you can use those parameters to build up a filter to POST, using those parameters to get the data. History would still work fine in that scenario.
@DanielLorenz Ah okay that makes sense. I think I misunderstood what you were saying.
|
114

It seems that resource filtering/searching can be implemented in a RESTful way. The idea is to introduce a new endpoint called /filters/ or /api/filters/.

Using this endpoint filter can be considered as a resource and hence created via POST method. This way - of course - body can be used to carry all the parameters as well as complex search/filter structures can be created.

After creating such filter there are two possibilities to get the search/filter result.

  1. A new resource with unique ID will be returned along with 201 Created status code. Then using this ID a GET request can be made to /api/users/ like:

    GET /api/users/?filterId=1234-abcd

  2. After new filter is created via POST it won't reply with 201 Created but at once with 303 SeeOther along with Location header pointing to /api/users/?filterId=1234-abcd. This redirect will be automatically handled via underlying library.

In both scenarios two requests need to be made to get the filtered results - this may be considered as a drawback, especially for mobile applications. For mobile applications I'd use single POST call to /api/users/filter/.

How to keep created filters?

They can be stored in DB and used later on. They can also be stored in some temporary storage e.g. redis and have some TTL after which they will expire and will be removed.

What are the advantages of this idea?

Filters, filtered results are cacheable and can be even bookmarked.

Improve this answer

2 Comments

well this should be the accepted answer. You don't violate REST principles and you can make long complex queries to resources. It's nice, clean and bookmark compatible. The only additional drawback is the need for storing key/value pairs for created filters, and the already mentioned two request steps.
The only concern with this approach is, if you have date-time filters in query (or a constantly changing value). Then the number of filters to store in db (or cache) are innumerable.
21

I think you should go with request parameters but only as long as there isn't an appropriate HTTP header to accomplish what you want to do. The HTTP specification does not explicitly say, that GET can not have a body. However this paper states:

By convention, when GET method is used, all information required to identify the resource is encoded in the URI. There is no convention in HTTP/1.1 for a safe interaction (e.g., retrieval) where the client supplies data to the server in an HTTP entity body rather than in the query part of a URI. This means that for safe operations, URIs may be long.

Improve this answer

2 Comments

ElasticSearch also does GET with body and works well!
Yeah but they control the server implementation may not be tne xase on the interwebs.
13

As I'm using a laravel/php backend I tend to go with something like this:

/resource?filters[status_id]=1&filters[city]=Sydney&page=2&include=relatedResource

PHP automatically turns [] params into an array, so in this example I'll end up with a $filter variable that holds an array/object of filters, along with a page and any related resources I want eager loaded.

If you use another language, this might still be a good convention and you can create a parser to convert [] to an array.

Improve this answer

2 Comments

This approach looks nice, but there could be issues with using square brackets in URLs, see what-characters-can-one-use-in-a-url
@Sky This could be avoided by URI encoding the [ and ]. Using encoded representations of these characters to group query parameters is a well known practice. It's even used in JSON:API specification.
5

FYI: I know this is a bit late but for anyone who is interested. Depends on how RESTful you want to be, you will have to implement your own filtering strategies as the HTTP spec is not very clear on this. I'd like to suggest url-encoding all the filter parameters e.g.

GET api/users?filter=param1%3Dvalue1%26param2%3Dvalue2

I know it's ugly but I think it's the most RESTful way to do it and should be easy to parse on the server side :)

Improve this answer

2 Comments

I would not go for this approach as it has no clear arguments. The only readable argument here is filter which then has an URL encoded value. If you want to go for this approach, I would adjust this to GET api/users?mode=filter&paramA=valueA&paramB=valueB that way you could have a mode=filter, mode=search, mode=exclude, ...
This is useful in case where there is huge amount (n) of possible params (which is not problem for front), but in backend with proposed approach you have just one param (filter) instead of n(huge num) optional params or dynmaic param handling.
1

Don't fret too much if your initial API is fully RESTful or not (specially when you are just in the alpha stages). Get the back-end plumbing to work first. You can always do some sort of URL transformation/re-writing to map things out, refining iteratively until you get something stable enough for widespread testing ("beta").

You can define URIs whose parameters are encoded by position and convention on the URIs themselves, prefixed by a path you know you'll always map to something. I don't know PHP, but I would assume that such a facility exists (as it exists in other languages with web frameworks):

.ie. Do a "user" type of search with param[i]=value[i] for i=1..4 on store #1 (with value1,value2,value3,... as a shorthand for URI query parameters):

1) GET /store1/search/user/value1,value2,value3,value4

or 

2) GET /store1/search/user,value1,value2,value3,value4

or as follows (though I would not recommend it, more on that later)

3) GET /search/store1,user,value1,value2,value3,value4

With option 1, you map all URIs prefixed with /store1/search/user to the search handler (or whichever the PHP designation) defaulting to do searches for resources under store1 (equivalent to /search?location=store1&type=user.

By convention documented and enforced by the API, parameters values 1 through 4 are separated by commas and presented in that order.

Option 2 adds the search type (in this case user) as positional parameter #1. Either option is just a cosmetic choice.

Option 3 is also possible, but I don't think I would like it. I think the ability of search within certain resources should be presented in the URI itself preceding the search itself (as if indicating clearly in the URI that the search is specific within the resource.)

The advantage of this over passing parameters on the URI is that the search is part of the URI (thus treating a search as a resource, a resource whose contents can - and will - change over time.) The disadvantage is that parameter order is mandatory.

Once you do something like this, you can use GET, and it would be a read-only resource (since you can't POST or PUT to it - it gets updated when it's GET'ed). It would also be a resource that only comes to exist when it is invoked.

One could also add more semantics to it by caching the results for a period of time or with a DELETE causing the cache to be deleted. This, however, might run counter to what people typically use DELETE for (and because people typically control caching with caching headers.)

How you go about it would be a design decision, but this would be the way I'd go about. It is not perfect, and I'm sure there will be cases where doing this is not the best thing to do (specially for very complex search criteria).

Improve this answer

15 Comments

Yo, if you (someone, whoever/whatever) things approprite to downvote my answer, would it hurt you ego to at least put a comment indicating what exactly do you disagree with? I know it's the interweebz, but ... ;)
I didn't downvote, but the fact that the question starts with: "I'm currently designing and implementing a RESTful API" and your answer starts with "Don't fret too much if your initial API is fully RESTful or not" feels wrong to me. If you're designing an API you are designing an API. The question is asking how to best design the API, not about whether the API should be designed.
The API is the system, work on the API first, not the backend plumbing, the first implementation could/should just be a mock. HTTP has a mechanism for passing parameters, you are suggesting it be reinvented, but worse (ordered parameters instead of name value pairs). Hence the down vote.
@gardarh - yes, it feels wrong, but at times, it is pragmatic. The primary objective is to design an API that works for the business context at hand. If a fully RESTFULL approach is appropriate to the business at hand, then go for it. If it is not, then don't go for it. That is, design an API that meets your specific business requirements. Going around trying to make it RESTfull as its primary requirement is no much different from asking "how do I use the adapter pattern in X/Y problem." Don't shoe horn paradigms unless they solve actual, valuable problems.
I view a resource as some collection of state, and parameters as a means for manipulating the representation of that state parametrically. Think of it this way, if you could use knobs and switches to adjust how the resource is displayed (show/hide certain bits of it, order it differently, etc...) those controls are params. If it's actually a different resource ('/albums' vs '/artists', for instance), that's when it should be represented in the path. That's what is intuitive to me, anyway.
|

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.