0

Is a REST method which returns dynamically generated random data each time that it is accessed considered safe?

According to RFC 2616 (emphasis mine):

...

In particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe". This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested.

Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.

My understanding from this is that the method should be considered safe as the only action is retrieval. The state of the server is not changing with multiple calls (though the result may be different) as any side effects generated would be the same (such as logging that the endpoint was accessed).

I'm not sure if this is the case though as there is no true resource being accessed since the data is generated dynamically. I also could be misunderstanding the concepts of safe methods, idempotence, and how these concepts relate to REST APIs. Any information is very much appreciated!

  • I think ‘safe’ means that the data (resource) is not being mutated. I don’t think your example of randomly generated data is considered one way or the other in the excerpt. – Matthew James Briggs Jun 15 at 5:05
3

It is important to look at why we want to have safe and idempotent methods.

ReST is an architectural style for large-scale information systems. Networks are inherently unreliable. So, you have to deal with things like lost, re-ordered, delayed, and duplicated messages, and strategies like caching.

Idempotent methods allow you to repeat a request without worrying about duplicating a side-effect. So, if you make an idempotent request, and you don't get a response, you can simply repeat the request without having to check whether or not the previous request reached the server and it was only the response that got lost. Idempotent methods also allow a caching proxy to return a cached response without even forwarding the request to the server if it sees the same idempotent request twice.

Safe methods have all the guarantees of idempotent methods, and more.

So, the question you need to ask yourself is: is there any problem, if a caching proxy in between simply always returns the same response for GET /random-number?

  • 1
    As long as it's chosen by fair dice roll. – jonrsharpe Jun 15 at 8:12
  • @jonrsharpe - I believe Jorg means that there is a caching proxy in between which caches the initial response and never returns a different value. Ever. Great for certain dice games (your example), but lousy for randomness. If the data is truly random (“CSRNG” random), caching would have to be disabled via a cache control directive. But that’s true in the general sense, not the stricter “ReST Theology” sense. – Julie in Austin Jun 17 at 2:28
2

According to RFC 2616 (emphasis mine)

Note that RFC 2616 is obsolete; it has been replaced by RFC 7230->RFC 7235. "Safe" is now defined in RFC 7231

Request methods are considered "safe" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe method is not expected to cause any harm, loss of property, or unusual burden on the origin server.

...The purpose of distinguishing between safe and unsafe methods is to allow automated retrieval processes (spiders) and cache performance optimization (pre-fetching) to work without fear of causing harm. In addition, it allows a user agent to apply appropriate constraints on the automated use of unsafe methods when processing potentially untrusted content.

I regularly use https://www.uuidgenerator.net/ when I need an identifier to use in a answer, and the API they provide is safe, even though the representation of that page changes every time I hit it (the Cache-Control header provided by the server specifies that the page should be re-fetched each time we need a representation of the resource).

I'm not sure if this is the case though as there is no true resource being accessed since the data is generated dynamically.

REST has a very flexible definition of resource

Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource.

Another way to consider this; imagine that producing new dynamically generated random data is expensive -- 1000 USD per pop. We certainly wouldn't want to be paying out that fee for spiders that are reviewing the site every day, or when that information is speculatively pre-loaded into the cache.

In such a circumstance, we would not provide access to this resource using safe methods; doing so sends the wrong message to the clients (and intermediate components). Instead, we would insist that access to the resource happen via POST, so that the machines would know not to do the wrong thing.

  • Very thorough! The note about the updated RFC was very helpful - I learned an important lesson about reading RFCs! To clarify with your uuidgenerator example: even though there may be some server state that is changed by the method, it is considered safe since the cache-control header is being sent which disables response caching; the API could still safely be crawled, but the case of caching is addressed with the header. To clarify the 1000USD example: if the act of crawling the page would result in undesired cost, we wouldn't use a safe method and instead use an unsafe POST method. – L. Steer Jun 21 at 2:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.