Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Nested Resources in REST/HTTP API URLs?

news.ycombinator.com

Post reply on HN
Print view View original

11–20 of 72 posts

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#11

Post by nickzelei »

alganet wrote: post #3

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 oth…

This is the right answer here. This design simplifies APIs and makes them much more straight forward as it more easily lets you operate on the data.

Nesting entities seems like the right approach at first but can turn into a nightmare as you continue to build things out.

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#14

Post by eyelidlessness »

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!

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#15

Post by mnutt »

vermon wrote: post #4

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?

In some cases there might be a next stage of complexity where you have users with access to multiple tenants who are browsing them in different tabs. Then putting the organization as the top level in _every_ URL helps signal intent; otherwise you have to take other precautions that someone isn't on a tab with Organization A, clicks "Post new article" button (-> POST /articles) and happens to have their session logged into Organization B and so creates the new article ere.

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#16

Post by mayank »

alganet wrote: post #3

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 oth…

> - /organizations/:id

> - /blogs/:id

The pragmatic, large-company-only counterpoint is the narrow edge case where:

- :id must be human-readable for "SEO reasons"

- there are many competing organizations and blogs to the point where there may be a name collision.

Although in that case, I'd still suggest:

/:organization-name/:blog-name

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#17

Post by Vanit »

alganet wrote: post #3

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 oth…

Yep this is it. If you nest IDs you just end up burdening all consumers with having to mimic your hierarchical structure when they don't need to.

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#18

Post by yawnxyz »

alganet wrote: post #3

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 oth…

I'd do it this way as well for most cases.

Complicated URLs are hard to remember and annoying to share. The one benefit of the nested URL is that you get is of being able to "inspect" what organization or section or comment a piece of content belongs to. This is probably a rare edge case and something you should only implement if it makes your system much more usable, for some reason.

e.g. I'd probably rather have podcastsite.com/:podcastname/:podcastepisode/:comment_id

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#19

Post by pan69 »

alganet wrote: post #3

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 oth…

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

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

And:

/organizations/123/blogs -> /blogs?organization_id=123

Because what you're doing is just applying a filter to an index of blog resources.

I.e. the "/organizations/123/blogs" route is simply an alias to "/blogs?organization_id=123" which you can just redirect to in your gateway.

Re: Ask HN: Nested Resources in REST/HTTP API URLs?

#20

Post by jackconsidine »

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...

Post reply on HN