Which REST API url structure should I take?

Question

I am wondering which API url scheme should I use.

I am designing multi-site project so that the URL can looks like:

[GET] /website/1
[GET] /website/1/category
[GET] /website/1/product

Which is life saving since we inject the root website id for the resources we want to list

but

there are cases when this is not important, mainly during update or delete:

[PUT] /website/1/category/1234

This way I would only make the backend server code execution longer since I don't need the website id to update category 1234.

This could be as good as

[PUT] /category/1234

Is there any decent argument for choosing one over another solution? I don't see the /website/1/category/1234 as consistency example since it's a consistency that generates a boilerplate execution.

• Robert Harvey: restfulapi.net/resource-naming
• Eric Stein: @RobertHarvey There is no such thing as "REST Resource Naming Best Practices". REST URIs are opaque. A website such as this one which prominently claims otherwise is just wrong.
• Robert Harvey: @EricStein: You'll get no argument from me. Still, it is a good starting point.

Answer 1

There are two (main) schools of thought on this. The first is that you create URIs that are human readable and that you can construct from an understanding of the structure. The other is that URIs should not be (or need not be) understandable or 'constructable'. In the latter school, all URIs are retrieved from the server by traversing from a root resource as you describe in the first part of the question.

If you (or your team/client) are in the first school, the first option is probably more preferable because the second is inconsistent.

If you are in the second school, it doesn't matter either way because no one should be attempting to construct the paths. You would just return the ids of the categories in your GET directory listings and on POST calls that create those resources.

The one practical advantage of the first approach in both cases is that provides a minimal protect from errors or nefarious guessing. For example, if your id's are sequential, a user on one site can guess at URIs belonging to another site.

• Bartłomiej Sobieszek: Thanks for the answer. The id guessing is not a problem since there will be authorization method, eventually the id will be hashed but I don't care that much about it. Not a security hole if correctly protected with permissions matrix. I think I will use the solution of providing longer path for the URL, AND include HateOAS on top of that so any long and complex url will not be constructed on client side. What are your thoughts on this?
• JimmyJames: @BartłomiejSobieszek Whether you want to use URI construction is a bit of a style question. The big disadvantage of that is if clients use that approach, you cannot change your URI structures without breaking them. If you provide constructable URIs, clients are likely to backwards engineer the structure. Then, later, if you change your structures, their code will break. The question is whether you care about that i.e what is the power dynamic between the clients of the API and you? If you are in the subordinate position, you may end up locked into this approach.

Answer 2

Another way to look at this is what can be a base URI and can /website/1/ be a base URI?

Please have a look at Establishing a Base URI. There are several ways to decide how a URI can be considered as Base URI. Specifically to your question, if somehow a client received e.g. http://example.site/website/1 to retrieve a website and website is not part of some other entity, then that can be a Base URI.