9 ms·

Just do: - /organizations/:id - /blogs/:id - /sections/:id - /threads/:id - /comments/:id Why? What determines how resources are related are links, not p

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

nickzelei 4y ago
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.
mayank 4y ago
> - /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
- djbusby 4y ago
  What if the company changes name?
  - nirimda 4y ago
    What if you're using ids and two organisations merge? Whatever solution works for organisation ids will work for organisation names.
- slekker 4y ago
  What about /blogs/:id?organization=:id, doesn’t it solve the issue?
- deleted 4y ago
  [deleted]
Vanit 4y ago
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.
- Twisol 4y ago
  It's worth noting that hierarchy itself isn't the problem, only hierarchy that isn't necessary for identifying a resource. If you happen to start comments on every post from 0 -- something like a (post_id, comment_id) primary key constraint on your comments table -- then it's natural to have a `/posts/1/comments/2` structure for your URLs. Under this data model, if you just had `/comments/2`, you wouldn't know enough to actually identify the comment -- just that it's the second comment on some post. Whether it's a good idea to use this kind of composite key is a separate question, though.
yawnxyz 4y ago
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
- alganet 4y ago
  A cool way of reaping benefits of both approaches is to separate client side and server side URLs. The thing after the '#', which has been called many things in the past (hash fragment, I guess), never goes into the server, so you can play with it using JavaScript to make it meaningful to users, while keeping it simple and flat on the real HTTP requests.
  - Shorn 4y ago
    That's a neat idea. It's like a self-contained documentation / "comment" of the URL. `#` is even fairly well-known commenting character.
pan69 4y ago
> 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.
Brystephor 4y ago
The data model matters doesn't it? If it's /org/orgId/blog/blogId and a user has access to only a single orgId and needs to be logged in then doing it in /blog/blogId makes sense. But if a user has acess to multiple orgs via different orgIds, then it makes more sense to do the former with /org/orgId/blog/blogId because then the page is sharable via URL. If you do just /blog/blogId that prevents a user from easily accessing a new organization (unless you use query parameters)
- mtrpcic 4y ago
  Just gives blogs unique IDs regardless of the organization. No two blogs ever have the same ID. Now the route doesn't need to provide the Organization ID, because that association lives in the data store for your application and you can infer it.
arinlen 4y ago
I'd also add that using a flat resource hierarchy also makes it slightly simpler to peel off a resource set, such as /organizations/:id, into a dedicated microservice.
mamoriamohit 4y ago
This is good for fetching a single item. What if you want to list resources? Eg. List all comments of a blog? It has to be GET /blog/:blogid/comments Then, how about creating a new comment? It'll be POST /blog/:blogid/comments When both of these have the blog's hierarchy in the URL, should we take it away when fetching a single item? Or the stay consistent, we should simply do: /blog/:blogid/comments/:commentid It's hard.
- arinlen 4y ago
  > This is good for fetching a single item. What if you want to list resources? You're just asking for one of the most basic features in resource-oriented architectures: query a collection resource with a filter predicate and possibly pagination. GET /comments?blog=<blogId> > Then, how about creating a new comment? Same thing: just POST it to /comments with a relevant request document, such as {"blog":<blogId>,"comment":<blah blah blah>} Your POST request then receives a response with a link to the newly-created comment resource, and that's it. > When both of these have the blog's hierarchy in the URL, should we take it away when fetching a single item? Resources do not have a hierarchy per se. You've just been passing request parameters through the path. That's it. > It's hard. Not really. It's a matter of understanding that resource-based architectures just deal with resources, and not resource hierarchies which don't really exist per se. What you mean by hierarchy is actually just passing parameters through the path, but those parameters can be passed elsewhere.
- xendipity 4y ago
  In this case, I think of this as more of a search endpoint than a list. What would you think about using a parameter to specify the relation? i.e. GET /comments?blogId=<id>
- alganet 4y ago
  List all comments of a blog: GET /blog_comments/:blogId Creating a new comment: POST /comments (blog_id, author_id, category_id all in the post body) Single comment: GET /comments/1234 You can pretty much follow all the same normalization rules you would for a SQL database. /blog_comments is a kind of query in a virtual N-to-N resource that maps blogs to comments, get it? Consider for example, "all posts that this particular author commented on". That would be insane to put into a hierarchy URL. For a flat one, you can just: GET /commented_by/:authorId Boom, done. Sometimes, you'll need more than one id, of course, but that does not imply "nesting". Consider "all posts where these two authors interact on comments": GET /discussions_involving/:authorId1/:authorId2 There is a cap in what you can do with a hierachy, and the web is not a filesystem with folders, it's a graph with unlimited possibilities.
contentboot 4y ago
This seems like the most traditional and respectful of REST way to go. You could try a HATEOAS approach if you want to get a bit more fancy. https://restfulapi.net/hateoas/ https://restfulapi.net/hateoas/ If you are following REST strictly there should be only objects, actions and verbs.
- arinlen 4y ago
  > If you are following REST strictly there should be only objects, actions and verbs. Not quite. That would be a resource-based architectures much like REST, but REST dials requirements a notch higher, with stuff like adding capabiliy-discovering semantics to resources such as navigation links to related resources and operations to express it's state and state-changed, in the form of HATEOAS.
otikik 4y ago
This would be my recommendation, especially if you use UUIDs or some other long string as identifiers
tasubotadas 4y ago
That's a poor advice. APIs are consumed by humans first. Machines don't care about your structure. HATEOS is the part that actually doesn't matter in practice.
- deleted 4y ago
  [deleted]
- alganet 4y ago
  Both machines and humans can easily follow links, that's precisely why hypermedia was invented. The part for humans is the HTML form I'm typing on. Humans _can_ type in HTTP/1.1 non-chunked requests by hand, but I don't see it that often. For developers, you might think that the URIs are "the UI" of an API, but they were not designed to be used in that way. We were meant to use the HTML rel= attribute to inform our machine clients on how to navigate links. We still do, sometimes. rel=stylesheet is a vestigial trace of that. rel=nofollow still informs clients of irrelevant URLs to this day. We use HATEOAS all the time, we're just not using the standards designed to express them. A complete API schema (what seems to be the cool thing these days), in the eyes of REST, is nothing but a giant complex hypermedia form written in an unspecified media type. The "blog_id" is nothing but a lofi link, and so on.
mariusor 4y ago
I can think of at least one example where this wouldn't work: when blog ids are not unique across organizations.

nickzelei 4y ago

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.

mayank 4y ago

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

djbusby 4y ago
What if the company changes name?
- nirimda 4y ago
  What if you're using ids and two organisations merge? Whatever solution works for organisation ids will work for organisation names.
slekker 4y ago
What about /blogs/:id?organization=:id, doesn’t it solve the issue?
deleted 4y ago
[deleted]

Vanit 4y ago

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.

Twisol 4y ago
It's worth noting that hierarchy itself isn't the problem, only hierarchy that isn't necessary for identifying a resource. If you happen to start comments on every post from 0 -- something like a (post_id, comment_id) primary key constraint on your comments table -- then it's natural to have a `/posts/1/comments/2` structure for your URLs. Under this data model, if you just had `/comments/2`, you wouldn't know enough to actually identify the comment -- just that it's the second comment on some post. Whether it's a good idea to use this kind of composite key is a separate question, though.

yawnxyz 4y ago

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

alganet 4y ago
A cool way of reaping benefits of both approaches is to separate client side and server side URLs. The thing after the '#', which has been called many things in the past (hash fragment, I guess), never goes into the server, so you can play with it using JavaScript to make it meaningful to users, while keeping it simple and flat on the real HTTP requests.
- Shorn 4y ago
  That's a neat idea. It's like a self-contained documentation / "comment" of the URL. `#` is even fairly well-known commenting character.

pan69 4y ago

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

Brystephor 4y ago

The data model matters doesn't it? If it's /org/orgId/blog/blogId and a user has access to only a single orgId and needs to be logged in then doing it in /blog/blogId makes sense. But if a user has acess to multiple orgs via different orgIds, then it makes more sense to do the former with /org/orgId/blog/blogId because then the page is sharable via URL. If you do just /blog/blogId that prevents a user from easily accessing a new organization (unless you use query parameters)

mtrpcic 4y ago
Just gives blogs unique IDs regardless of the organization. No two blogs ever have the same ID. Now the route doesn't need to provide the Organization ID, because that association lives in the data store for your application and you can infer it.

arinlen 4y ago

I'd also add that using a flat resource hierarchy also makes it slightly simpler to peel off a resource set, such as /organizations/:id, into a dedicated microservice.

mamoriamohit 4y ago

This is good for fetching a single item. What if you want to list resources? Eg. List all comments of a blog? It has to be GET /blog/:blogid/comments Then, how about creating a new comment? It'll be POST /blog/:blogid/comments When both of these have the blog's hierarchy in the URL, should we take it away when fetching a single item? Or the stay consistent, we should simply do: /blog/:blogid/comments/:commentid It's hard.

arinlen 4y ago
> This is good for fetching a single item. What if you want to list resources? You're just asking for one of the most basic features in resource-oriented architectures: query a collection resource with a filter predicate and possibly pagination. GET /comments?blog=<blogId> > Then, how about creating a new comment? Same thing: just POST it to /comments with a relevant request document, such as {"blog":<blogId>,"comment":<blah blah blah>} Your POST request then receives a response with a link to the newly-created comment resource, and that's it. > When both of these have the blog's hierarchy in the URL, should we take it away when fetching a single item? Resources do not have a hierarchy per se. You've just been passing request parameters through the path. That's it. > It's hard. Not really. It's a matter of understanding that resource-based architectures just deal with resources, and not resource hierarchies which don't really exist per se. What you mean by hierarchy is actually just passing parameters through the path, but those parameters can be passed elsewhere.
xendipity 4y ago
In this case, I think of this as more of a search endpoint than a list. What would you think about using a parameter to specify the relation? i.e. GET /comments?blogId=<id>
alganet 4y ago
List all comments of a blog: GET /blog_comments/:blogId Creating a new comment: POST /comments (blog_id, author_id, category_id all in the post body) Single comment: GET /comments/1234 You can pretty much follow all the same normalization rules you would for a SQL database. /blog_comments is a kind of query in a virtual N-to-N resource that maps blogs to comments, get it? Consider for example, "all posts that this particular author commented on". That would be insane to put into a hierarchy URL. For a flat one, you can just: GET /commented_by/:authorId Boom, done. Sometimes, you'll need more than one id, of course, but that does not imply "nesting". Consider "all posts where these two authors interact on comments": GET /discussions_involving/:authorId1/:authorId2 There is a cap in what you can do with a hierachy, and the web is not a filesystem with folders, it's a graph with unlimited possibilities.

contentboot 4y ago

This seems like the most traditional and respectful of REST way to go. You could try a HATEOAS approach if you want to get a bit more fancy. https://restfulapi.net/hateoas/ https://restfulapi.net/hateoas/ If you are following REST strictly there should be only objects, actions and verbs.

arinlen 4y ago
> If you are following REST strictly there should be only objects, actions and verbs. Not quite. That would be a resource-based architectures much like REST, but REST dials requirements a notch higher, with stuff like adding capabiliy-discovering semantics to resources such as navigation links to related resources and operations to express it's state and state-changed, in the form of HATEOAS.

otikik 4y ago

This would be my recommendation, especially if you use UUIDs or some other long string as identifiers

tasubotadas 4y ago

That's a poor advice. APIs are consumed by humans first. Machines don't care about your structure. HATEOS is the part that actually doesn't matter in practice.

deleted 4y ago
[deleted]
alganet 4y ago
Both machines and humans can easily follow links, that's precisely why hypermedia was invented. The part for humans is the HTML form I'm typing on. Humans _can_ type in HTTP/1.1 non-chunked requests by hand, but I don't see it that often. For developers, you might think that the URIs are "the UI" of an API, but they were not designed to be used in that way. We were meant to use the HTML rel= attribute to inform our machine clients on how to navigate links. We still do, sometimes. rel=stylesheet is a vestigial trace of that. rel=nofollow still informs clients of irrelevant URLs to this day. We use HATEOAS all the time, we're just not using the standards designed to express them. A complete API schema (what seems to be the cool thing these days), in the eyes of REST, is nothing but a giant complex hypermedia form written in an unspecified media type. The "blog_id" is nothing but a lofi link, and so on.

mariusor 4y ago

I can think of at least one example where this wouldn't work: when blog ids are not unique across organizations.