REST : Static API design

Question

Lets say, I have a scenario where I have to expose an api to fetch supported shirt sizes(small , medium and large)

My initial thought was /v1/shirts/sizes - But this clashes with the existing fetch shirt by id api. v1/shirts/:id.

My friend is suggesting, we can have resource named metadata, which can be used to list all static information throughout our application. Something like /v1/metadata/shirtsizes , /v1/metadata/languages etc.

But I am not happy with having metadata api since it have completely unrelated sub-resources(shirtsizes , supported-lanugages)

How to handle this scenario? Is there any way to achieve it?

• amon: Are there any constraints on the :id placeholder? E.g. if the ID is numeric, then sizes won't conflict. Alternatively just add an endpoint like /v1/shirt-sizes. Not as elegant, still better than introducing a metadata concept without strong justification.
• Jeevi: Id is string , which can contain a special char -
• Ewan: v1/shirtsizes seems logical

Answer 1

REST doesn't care what spelling conventions you use for your URI. An identifier like

/ac8a98b3-553a-4eb3-9878-e143f3f52a4e

is fine.

REST doesn't particularly care about clashes with "fetch by id". You are allowed to write request handlers that branch. See, for example, the rails routing conventions, which specifically use hints that sit in the same path segment as identifiers

/photos/new
/photos/:id

REST doesn't particularly care what information is encoded within the path or within the query

/v1/shirts/:id
/v1/shirts?sizes

(Which is not to say this distinction doesn't matter - in particular, HTML form processing treats the hierarchical path elements differently than the non-hierarchical query. But the difference between the two is purely mechanical.)

REST certainly doesn't care about the order of path segments

/v1/sizes/shirts

Again, that's fine.

(We design path hierarchies not for the information that they communicate, but instead so that we can conveniently leverage standardized resolution of relative references.)

Part of the point of REST is that the identifiers are just identifiers; the general purpose components don't attempt to extract information from them. So you can use any spellings that make sense locally.