Nested Resources in REST/HTTP API URLs?

Just do:

- /organizations/:id

- /blogs/:id

- /sections/:id

- /threads/:id

- /comments/:id

Why?

What determines how resources are related are links, not patterns in the URL. It's a graph, the URLs are just nodes, the links are what connect them.

If you _want_ to have some sort of hierarchy in the URL, you can redirect:

- /organizations/123/blogs/1234 -> /blogs/1234

Then each resource expresses how it is related to others using links (hrefs, or other mechanism for orther media types).

URIs can be anything like /ajndkandkjnasd, totally unreadable for humans. If it is a resource that contains links that can be followed, then it is a system that answers to a uniform interface, and that is the part of the REST dissertation that really matters (the other stuff are just implications of having such uniform interface).

For machine APIs, payloads could use "comment_id", "thread_id" and so on referring to a single resource. If any API users need to build URLs, they would do so by using a single property of the data (which is good enough as a link for me nowadays, for private APIs at least).

A problem with nested URLs like /organizations/:organizationId/blogs/:blogId/sections/:sectionId is that when you are manipulating a section from the frontend, you don't only need to keep and pass around their sectionId, but also their organisationId and blogId everywhere. Often you'll already have those, but sometimes not and it'll be annoying, you'll have to make more complex code with functions taking more parameters than necessary. From the backend, you'll need to check that all those ids are consistent and match.

It's also possible you will need at some point to re-use sub objects in a new context, so you'll have different kinds of paths to query those sub objects.

I'd go with Python's guideline "Flat is better than nested" here, and in doubt, follow it.

I think nested is only appropriate if you want to ensure the requester knows the oragnisationId, the blogId and the threadId of a particular comment to access it. Otherwise, it will lead to more complexity everywhere.

While things often have parents and children, they also very frequently stand alone. Also, sometimes you don't want to leak private data (org id's) in public content (a blog post)

What I recommend is follow the resource standards from something like jsonapi, and organize your routes like this:

/organizations/:organization_id

/organizations/:organization_id/blogs -> returns a list of links to blogs (maybe including the very most basic data, like blog title and byline)

/blogs/:blog_id -> one blog, has a link to organization, for going "up" the hirearchy, but only returned for authenticated users (if that's necessary in your use case)

/blogs/:blog_id/sections -> links to list of sections

/blogs/:blog_id/threads -> links to list of threads

/threads/:thred_id -> one thread, but links to parents as above

/sections/:section_id -> same as threads

you get the idea.

I've done it this way and I feel like it ends up being very easy to wrap my head around where things are, and how they relate to one another.

One of my favorite example APIs is stripe. the layout makes sense, routes make sense, and it's a very complex system which becomes easy to understand and the routes aren't insanity, if you are looking for a very public example

It doesn’t actually matter unless your API is expected to be consumed without any particular entry point. If you can expect users to enter at specific points, you can represent state as hypertext and give them links (URLs) rather than ids. They don’t need to know or care about your URL patterns, they just need to follow the hyperlinks you provide.

You can do the same even if some entry points are known, and then I'd follow the approach of /top-level/:id, because it’s at least a predictable way to start. If further API access requires discovery, go wild and format your URLs how it works best for your service. Just keep them unique and stable, because stable URLs are cool!

The Github API [0] is a good place to look- it seems like they thought a lot about their hierarchies.

They do things like

/orgs/ORG/repos /repos/OWNER/REPO/issues

In other words, GH scopes their endpoints usually one maybe two layers. I think conceptually that makes a lot of sense

[0] https://docs.github.com/en/rest/repos/repos#list-organizatio...

> /organizations/:organizationId/blogs/:blogId OR /blogs/:blogId (and get the organization from somewhere else like an auth token)

You make it sound like the blog posts are keyed by (organizationId, blogId). If this is so, then /organizations/:organizationId/blogs/:blogId is clearly superior. But if blogId alone is sufficient to identify the blog post, then /blogs/:blogId is very likely to be wiser.

But you also make it sound like sessions might be scoped to an organization, that organization is, for API purposes, a singleton. In that case, /organizations/:organizationId (the route, not the prefix) would not make a great deal of sense: it should either be just /organization or not exist, and be removed as a prefix from other things.

This reasoning can be applied to the rest as well.

In theory, HATEOS is designed to resolve this problem.

Quick 3 min draft example: https://gist.github.com/djames-bloom/2131d021a8f6d3d09c5a808...

One way to think about it might be to think of REST as RPC rather than folder nesting. E.g. `/[param_name]/[value]/..`

So if you can find blogs just by their blogId, then `/blogs/:blogId` makes sense since you only provide the necessary parameters. `/organizations/:organizationId/blogs/:blogId` would imply that `blogId` is not unique across organizations. This may also make sense if that's how it is.

So, I generally do it the nested way: organizations/:organizationId/blogs/:blogId

The other post on this thread are accurate, in that normally keeping it simpler is better, but in this case I disagree.

With the nested approach you have the ability to do multiple levels of validation and mitigate a lot of key guessing attacks.

Imagine a different scenario:

facility/:facility_id/provider/:provider_id/patient/:patient_id

Vs

patient/:patient_id

In the first case there are three tokens I'd need to possess or guess in order to access a patient record. In the second, there's just one.

The implementation will still only grab the patient id for the query, but it'll validate that the two other keys are correct as well.

It also makes role scoping easier. I.e. my role grants admin access to all patients in a facility. Middleware to validate the access is a lot easier to implement if you have all those keys in the query string. Declarative permissions on the routes are a lot easier.

If it’s strictly a tree of relationships (always 1:many) then there are some benefits to having nested IDs. You can do things like attach permissions to the root of the tree, and logging is often clearer (the owner is right there in the URL).

However as soon as you need a M:M or many:1 relationship this breaks down. If a blog can be shared between multiple orgs, how do you represent that?

Therefore as others have recommended, a single ID per URL with a sub-endpoint for the nested list like /organizations/:organizationId/blogs/ (but no two-ID endpoints) is the generalizable and future-proof option. I strongly prefer to keep all the state in the URL rather than hitting /blogs/ and getting the org implicitly from the auth state. Way harder to debug if the auth context can change what results your API produces.

Consider using something like https://google.aip.dev/.

Consistency across an API surface is more valuable than local optimizations.

In case the organisation is basically a tenant in multi-tenant application I would leave it out of the API and resolve it in another way, but if it is not I would leave it in. Does that make sense?

Why reinvent the wheel? Just use a common standard... I prefer https://jsonapi.org/.

I find that having both /foo/:fooId and /bar/:barId/foo/:fooId to basically result in duplicate code/tests or unnecessary complexity. I'll allow /bar/:barId/foo/:fooId in an SPA router though (not http API). In probably most frameworks, each additional route probably encures a microscopic RAM/CPU cost.

The long form is more flexible because it gives you the full information about the state of the app. If you don't include the blogId in the URL, the front end will not know which blog the section or comment belongs to until it has finished loading from the server... So in the case of a single-page app, you can't show a 'Go back to blog' button in the UI until the page has finished loading... Though it's trivial to do if the blogId is in the URL.

A common pattern I follow with URLs is that I sometimes allow the user to omit the final ID in the URL; in this case I do a front-end redirect to the URL with the ID of the main/default resource appended at the end - This is useful if the user account has (for example) a 'main blog' associated with it.

If average users will see the URL in their browser, make it meaningful. After all, it is a user interface.

  X blog.com/users/1234/posts/5678
  √ blog.com/tom-nook/thoughts-about-urls

Go for logical structure and your query patterns.

If you plan querying blogs per organization, then make it a su resource under the organization.

If you are planning only to get a full list, go for root level blogs.

If you are planning to do both then do both :-)

https://dev.tasubo.com/2021/08/quick-practical-introduction-...

Biggest issues with nested URLs are:

* may be harder to route if you break your app into services, you are now relying on the server implementation to have fast regex routing

* harder to version the data models, if I need to add path versioning I’m stuck versioning and breaking the entire tree

I seriously think we need a serious update to REST api urls. There is no rule that says it has to be this hard.

I would imagine something like graphql type of URL schema:

    api.xxx.com/{organizations: organizationId { blogs: blogId { sections: sectionId } } }

I would go for the hierarchical urls, like:

- /organizations/:organizationId/blogs/:blogId

- /organizations/:organizationId/blogs/:blogId/sections/:sectionId

- /organizations/:organizationId/blogs/:blogId/threads/:threadId/comments/:commentId

I do this because it expresses the structure and the constraints of the data. A blog cannot exist without being linked to an organisation. And then you typically have the following CRUD endpoints:

- /organizations/:organizationId/blogs, with GET and POST to retrieve a list of blogs belonging to an organization and to create a blog for an organisation

- /organizations/:organizationId/blogs/:blogId, with GET, PUT and DELETE to retrieve, update and remove a blog

The fact that you always have the :organizationId in the url likely means that you can easily verify authorization, because I assume you would have a link between the user and an organization and maybe that link would already be available in the access token.

I don't think it is a problem that the urls are heavily nested. The urls are not supposed to be manually entered, but are using from within an application. I like the use of HATEOAS links, because I don't really like the frontend trying to assemble urls by itself.

Also note that next to the hierarchical links, you might need some extra for search that are not hierarchical. For example, say that there is a need to search blogs across organizations. This could be provided using the following:

- /blogs?description=test&language=en

You can provide a search endpoint in the root for blogs. This endpoint could then return some kind of blog object with a reference to the actual blog location (like /organizations/34/blogs/11). When you use this approach, the frontend has no need to assemble urls and the structure or complexity of the url does not matter. Do note that the frontend still needs some generic "start" urls like the blogs search endpoint.

Additional advantage (like others have mentioned), is that with the hierarchical urls it becomes more difficult to "guess" an url. Altough, if you want to properly protect against that, you should transform the ids before putting them in the url and transform them back when reading them out of an incoming url, for example using symmetric encryption with a secret only known in the backend.

http://aip.dev describes Google's approach to this.

I'd do :organizationId/:blogId/:postId/:commentId/:threadId leaving out the description of what every value is for shorter urls. I think you can get away with this how those relationships are defined.

example.org/2/1/4/12/326