0

I have an API that generates a resource randomly when requested.

  1. What path could I use that would follow REST conventions?
    A - /generate/random.png
    B - /generators/random
    C - ?

  2. Should I place all my resources in a root like /api to differentiate them from web pages? (For example, I might want to display a HTML page at /generators)

  3. If the answer to 1 was similar to options A or B, what would exist at /generate?

1
  • Whenever possible, it's a good convention not to have verbs in the URI. Verbs (actions) should be specified using the HTTP code, not the URI itself. Other than that, format really does not matter. After all you're the one crafting the web service and can do whatever you want to do, just keep it consistent.
    – Andy
    Sep 8, 2016 at 15:17

1 Answer 1

4

REST doesn't care about URI design. As far as REST is concerned, the client should be considering the URI to be opaque. (Contrast this with your caching headers - REST cares rather a lot about ensuring that intermediary components can correctly participate in the work being done.)

I have an API that generates a resource randomly when requested.

That's a rather peculiar remark in the context of REST. Resource and representation are important terms in REST, and are not interchangeable.

What I expect you intend is that your API includes a resource that generates a random representation when requested. Something like a UUID Generator?

Since REST doesn't express an opinion on the spelling of URI, you should fall back on your local URI design guidelines. These normally recommend that resources be identified by nouns, and that path segments express hierarchy.

/generators/random

"/generators" is fine, as it suggests that you are identifying a resource that is part of some collection. "random", being an adjective, isn't so good. The next useful step is probably to ask "random what?" Guessing from the first of your attempts, these might be reasonable choices

/generators/randomImage
/generators/randomPNG
/generators/image?random
/generators/png?random

Part of the point of REST is that implementations can be decoupled from services - the representation of a resource produced by the origin server might be loaded directly from the file system, or pulled directly out of a key value store, or produced by invoking a function, or by delegating the work to another endpoint. So you are probably better off identifying your resources by what instead of how.

So these choices are much better, because they better express the representation (which is a representation of an image, not a representation of a random image generator).

/images/random
/images/pngs/random

Should I place all my resources in a root like /api to differentiate them from web pages?

Maybe. REST doesn't care about spelling. Clients should just be following whatever links you give them, so the important thing is to make sure that your published bookmarks are reasonable. Some services use a different host to distinguish the api resources from the document resources; but many use a prefix path segment as you suggest.

If the answer to 1 was similar to options A or B, what would exist at /generate?

There might not be anything there. The fact that there is a resource with an identifier in the pattern of a member of a collection does not in any way imply that there is also a resource for the collection itself. You can happily 404 any requests to that if you like; clients of a REST api are supposed to navigate to published bookmarks and follow links -- playing guess-the-uri games is out of bounds.

In apis where the collection of resources is intended to be modified by the client, a common pattern would be to have a POST endpoint identified by the collection URI that allows the client to create new members in the collection.

Shouldn't I prefer something that conveys that it is generated randomly and requesting it again might not give the same result?

The caching headers, rather than the URI, are used by the REST components to determine if a previously fetched representation is still viable.

The audience to URI spelling is purely a human one.

The guiding principles are outlined in Cool URIs Don't Change; you want to continue to map the same URI to the same concept even when the underlying implementation for producing the representation changes.

/images/flowers/flowerOfTheDay
/images/flowers/latest
/images/flowers/random

So what you need to be considering in your design is whether the randomness of the image is core to the concept?

REST relies instead on the author choosing a resource identifier that best fits the nature of the concept being identified.

1
  • Thanks for the detailed answer. Yes, it generates a representation, my bad. "random" was a placeholder I used, the actual representation is that of a flower. Doesn't /images/flower suggest that it is a single image? Shouldn't I prefer something that conveys that it is generated randomly and requesting it again might not give the same result?
    – Hele
    Sep 8, 2016 at 5:58

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.