13

In order to stick with the REST concepts, such as safe operations, idempotency, etc., how can one implement a complex search operation involving multiple parameters?

I have seen Google's implementation, and that is creative. What is an option, other than that?

The idempotent requirement is what is tripping me up, as the operation will definitely not return the same results for the same criteria, say searching for customers named "Smith" will not return the same set every time, because more "Smith" customer are added all the time. My instinct is to use GET for this, but for a true search feature, the result would not seem to be idempotent, and would need to be marked as non-cacheable due to its fluid result set.

Brian Kelly
  • 19,067
  • 4
  • 53
  • 55
Pittsburgh DBA
  • 6,672
  • 2
  • 39
  • 68

3 Answers3

27

To put it another way, the basics behind idempotency is that the GET operation doesn't affect the results of the operation. That is, the GET can safely be repeated with no ill side effects.

However, an idempotent request has nothing to do with the representation of the resource.

Two contrived examples:

GET /current-time

GET /current-weather/90210

As should be obvious, these resources will change over time, some resources change more rapidly than others. But the GET operation itself is not germane in affecting the actual resource.

Contrast to:

GET /next-counter

This is, obviously I hope, not an idempotent request. The request itself is changing the resource.

Also, there's nothing that says an idempotent operation has NO side effects. Clearly, many system log accesses and requests, including GETs. Therefore, when you do GET /resource, the logs will change as a result of that GET. That kind of side affect doesn't make the GET not idempotent. The fundamental premise is the affect on the resource itself.

But what about, say:

GET /logs

If the logs register every request, and the GET is returning the logs in their current state, does that mean that the GET in this case is not idempotent? Yup! Does it really matter? Nope. Not for this one edge case. Just the nature of the game.

What about:

GET /random-number

If you're using a pseudo-random number generator, most of those feed upon themselves. Starting with a seed and feeding their results back in to themselves to get the next number. So, using a GET here may not be idempotent. But is it? How do you know how the random number is generated. It could be a white noise source. And why do you care? If the resource is simply a random number, you really don't know if the operation is changing it or not.

But just because there may be exceptions to the guidelines, doesn't necessarily invalidate the concepts behind those guidelines.

Resources change, thats a simple fact of life. The representation of a resource does not have to be universal, or consistent across requests, or consistent across users. Literally, the representation of a resource is what GET delivers, and it is up to the application, using who knows what criteria to determine that representation for each request. Idempotent requests are very nice because they work well with the rest of the REST model -- things like caching and content negotiation.

Most resources don't change quickly, and relying on specific transactions, using non-idempotent verbs, offers a more predictable and consistent interface for clients. When a method is supposed to be idempotent, clients will be quite surprised when it turns out to not be the case. But in the end, its up to the application and its documented interface.

Will Hartung
  • 115,893
  • 19
  • 128
  • 203
8

GET is safe and idempotent when properly implemented. That means:

  1. It will cause no client-visible side-effects on the server side
  2. When directed at the same URI, it causes the same server-side function to be executed each time, regardless of how many times it is issued, or when

What is not said above is that GET to the same URI always returns the same data.

GET causes the same server-side function to be executed each time, and that function is typically, "return a representation of the requested resource". If that resource has changed since the last GET, the client will get the latest data. The function which the server executes is the source of the idempotency, not the data which it uses as input (the state of the resource being requested).

If a timestamp is used in the URI to make sure that the server data being requested is the same each time, that just means that something which is already idempotent (the function implementing GET) will act upon the same data, thereby guaranteeing the same result each time.

Brian Kelly
  • 19,067
  • 4
  • 53
  • 55
2

It would be idempotent for the same dataset. You could achieve this with a timestamp filter.

Chriseyre2000
  • 2,053
  • 1
  • 15
  • 28
  • That will require massive logs so that I could reconstruct the representation "at that time", correct? The db will be updated via PUT, and any rows thus fetched in the future via that GET would have to be represented in their prior forms. While fulfilling idempotency, that is useless for us; we need query. What else can we do? I cannot be the only one wishing to implement search via REST. This is the only shortcoming that I can see. Even GET on an entity will not always return the same representation, because the entities are modifiable. How do people implement REST on top of dynamic entities? – Pittsburgh DBA Feb 10 '12 at 21:16
  • Why not have time expiring caches? – Chriseyre2000 Feb 10 '12 at 21:30
  • I love that idea. So, what's the gist? I store their query results for a pre-determined time so as to re-serve that representation? – Pittsburgh DBA Feb 10 '12 at 21:58
  • That's the idea. So the idempotentcy would be valid for say 5 mins. – Chriseyre2000 Feb 10 '12 at 22:04
  • Great. Will any REST evangelists be miffed, or is this acceptable according to the REST architecture? – Pittsburgh DBA Feb 10 '12 at 22:39