How do you deal with dynamic resources in a RESTful context?

Question

From what I understand of REST principles, URLs should represent a single resource, like a user or a product. How do you deal with resources that are random, or generated dynamically?

Suppose I create a resource called api.example.com/integer that returns a random integer. Would I still use GET to retrieve the integer? What would POST, PUT, and DELETE mean in this context?

What about URLs that represent behaviors? Suppose I create a resource called api.example.com/add that returns a sum of two numbers. If I wish to use this resource, do I use GET or POST to submit the numbers to be added?

Answer 1

I think GET would be appropriate for a random number. You would simply not allow POST, PUT, or DELETE on that resource.

For the sum, why not just:

getSum?addends=3,5,8

Reponse is 16.

POST is for when you want "the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line."

In this case, there's no need for the server to permanently accept/remember the addends, so POST is not appropriate.

Answer 2

It is not required that all resources support all verbs. That is what the OPTIONS verb is for to find out what verbs are supported.

I would say either of the following are pretty self explanatory

GET http://api.example.org/RandomInteger

POST http://api.example.org/RandomNumberMachine

Either could be valid. Just be careful that a GET request may get cached. If it does then you would not be getting a random result.

One of the main principles behind REST is that you model your urls are representing nouns, not verbs. So http://api.example.com/add is not an ideal url.

You could do

GET http://api.example.org/Summation?Values=2,4

or

POST http://api.example.org/AddingMachine

with some standard format entity body that contains the numbers to add.

On the surface it may seem pretty pedantic differentiating between an url that ends with "Add" and one that ends with "summation". However, this is a pretty simple example and the REST constraint is there to guide you towards a design that has certain desirable characteristics for distributed systems.

Many years ago people would argue the difference between

apple.bite()

and

bite(apple)

was not significant. I don't think too many would dismiss the distinction these days.

Answer 3

A resource is a resource. It can change, mutate, flip upside-down, or anything over its lifetime. Your resource in the first case isn't the random number, but the random number generator.

As Darrel said, it's not essential that all given resources support all HTTP's methods to be RESTful. Heck, I've a RESTful system that has various collection resources that allow GET (to fetch the collection), and POST (to append a new resource to the collection and possibly other collections at the same time, which then points to the newly created resource elsewhere), whereas other resources support GET, PUT (for updates), and DELETE. The key thing about a RESTful interface is that it's universally applicable--i.e., the protocol's methods can plausibly be applied in a general manner to many different kinds of resource--which is quite universally used, which would mean that all resources would need to implement the full interface.

HTTPs methods have well defined semantics. If their semantics apply to your resource in a sane manner, then implement them. If not, don't, or construct a separate resource that does.

In the context of HTTP, GET is a perfectly fine way to do something like your example of summation. Look at any search engine: they all use GET to do search, which is perfectly RESTful. Note though that your browser doesn't have out of band information on how to construct the URL of the resource representing your search, but by downloading a page containing a form, it downloads instructions on how to do it. This is part of the essence of HATEOAS and self description, which you're bound to stumble across as you learn more.

Answer 4

Just use some sort of RPC. REST isn't suited for every purpose.