Do RESTful service parameters have to be discoverable?

Question

Preamble: My understanding of REST is shallow at best, so any corrections or clarifications to my questions are welcome.

I have a situation where I need the user of a RESTful service to submit an arbitrary real positive number. I therefore assume I shouldn't require it in the url, even though the returned object should be the same, and should use a parameter instead (or is this assumption wrong?).

Given that, to conform to REST, does the parameter have to be discoverable somehow? I haven't been able to find anything that makes this clear to me.

If not, I further assume that the parameter needs to be documented in some other way, thus locking (a portion of) your current api, which, as I understand it, is not desirable, as resources should be found by following hypertext links rather than hard coding locations (and parameters in this case).

Assuming that parameters do have to be discoverable, is there some way of doing this in tastypie/django?

Answer 1

The "discoverable" part of REST typically refers to new resources (represented by URIs) returned by the server that weren't present before. Client applications can then choose to interact with those resources at their leisure.

For example, my application might GET a /library URI that returns a representation of what's in my local library. The data returned (encoded as a particular JSON-based media type) might look like this:

{
   "printedBooks" : "/library/books",
   "audioTapes" : "/library/tapes"
}

Now let's say a few months later I do the same GET on the same URI, I might now be returned this payload:

{
   "printedBooks" : "/library/books",
   "audioTapes" : "/library/tapes",
   "magazines" : "/library/magazines"
}

Now there's a new link to a magazines resource which I can presumably GET to find out what kind of magazines are available. If my client application doesn't care about it, no big deal - it just keeps using the other two resources as before. At some point in the future I might code up support for magazine searches too.

But if I've written some kind of super dynamic fancy-shmancy client application that can automatically adapt to the presence of this new resource, the users of the application get to use it without any effort at all. No upgrade was required: the server offered new functionality and the client made the most of it. Web browsers work in this way (albeit with a human driving a large part of the "dynamism").

To your specific question about parameters: those are typically specified as part of the server's API documentation. I don't know of any API that specifies parameter syntax in an automated fashion that would allow the client to be 100% generic and adaptable.

A well-defined RESTful API stands on the shoulders of the already-specified technologies which it uses (HTTP, URIs, content type negotiation, headers, etc) and leverages rather than redefines them. That's why I know that I can probably do a GET on the /library/magazines URI and request a JSON-based encoding, and it's pretty likely that I'll succeed. I know that if I have the URI to a particular magazine (say, /library/magazines/1234) then I can attempt to remove it by calling DELETE on it, and I'll know if it succeeded based on the returned HTTP status code. I didn't have to read any documentation or use any coding magic to do any of these things because these are actions already specified in HTTP.

However, to create a new magazine by POSTing to /library/magazines, I need to know what the representation of my parameter data should look like, regardless of whether I pass those parameters within the URI or within the body of the POST. That is data that needs to be specified out-of-band in the API documentation.

So, to summarize: RESTful servers can send clients back new information that they hadn't previously seen, and that's the heart of discoverability in REST. But when a client wants to send data to a server, it needs to send data that the server will understand and accept, and that's typically described in documentation.