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

Rules for REST API URI Design

blog.restcase.com

Post reply on HN
Print view View original

61–70 of 97 posts

Re: Rules for REST API URI Design

#61

Post by 3pt14159 »

tchow wrote: post #19

When doing something like `student/1245/courses` there will certainly be a scenario where you want a list of courses on their own as well. If planning ahead, does that warrant designing your route such as: `/courses` where you get a list of courses and `/courses?studentId=12345` Where you get courses scoped to a student... Or is it better to just recreate a separate route such that you have /courses AND student/2345/…

I follow JSON API v1.1, mostly anyway, see [1].

I not only create both paths, I also specifically create `relationships` links to control the relationship itself. That way, I have a restful way of, say, making a signed article anonymous. DELETE articles/2/relationships/author not that this doesn't delete the author just the relationship itself.

Your worry about the duplication of code is well founded, but slightly off. For what are called "related" links (articles/4/author) we only ever issue GETs. There are many reasons for this and you've started to catch onto a few of them.

This means a _lot_ of routes (over 300 right now), but with smart abstractions it's not so bad. I've been thinking of doing a weird fork of Rails based on how productive I've become. Basically I want to follow Rails but I want to override a lot of their decisions that don't fit JSON API's needs. Maybe one day.

[1] With a minor addition that I find helpful: I add an `also` link in the relationship body. GET articles/5/author would have `also` set to `users/45`. In this manner I can easily get a reference to the related resource and I make it explicit that the resource isn't dependant on it's relationship continuing to exist with the parent resource.

Re: Rules for REST API URI Design

#62

Post by 3pt14159 »

mkhattab wrote: post #58
tchow wrote: post #19

When doing something like `student/1245/courses` there will certainly be a scenario where you want a list of courses on their own as well. If planning ahead, does that warrant designing your route such as: `/courses` where you get a list of courses and `/courses?studentId=12345` Where you get courses scoped to a student... Or is it better to just recreate a separate route such that you have /courses AND student/2345/…

I believe '/courses' and 'student/1234/courses' mean two different things. The former implies a list of courses and the later implies an association between a student and a course. POSTing to '/courses' creates a new course. However POSTing to a 'student/1234/courses' creates a relationship/association between a student and a course. So, it's two different things IMO and not a duplication of logic.

This isn't true. Or at least not necessarily true. If you're referring to the JSON API spec you're conflating related and relationship links. The former is strictly for GETs (GET students/5/courses) and the later is for controlling the relationship itself (PATCH students/5/relationship/courses).

See here for more information:

http://jsonapi.org/format/upcoming/#crud-updating-to-many-re...

Re: Rules for REST API URI Design

#63

Post by 3pt14159 »

mkhattab wrote: post #58
tchow wrote: post #19

When doing something like `student/1245/courses` there will certainly be a scenario where you want a list of courses on their own as well. If planning ahead, does that warrant designing your route such as: `/courses` where you get a list of courses and `/courses?studentId=12345` Where you get courses scoped to a student... Or is it better to just recreate a separate route such that you have /courses AND student/2345/…

I believe '/courses' and 'student/1234/courses' mean two different things. The former implies a list of courses and the later implies an association between a student and a course. POSTing to '/courses' creates a new course. However POSTing to a 'student/1234/courses' creates a relationship/association between a student and a course. So, it's two different things IMO and not a duplication of logic.

This isn't true. Or at least not necessarily true. If you're referring to the JSON API spec you're conflating related and relationship links. The former is strictly for GETs (GET students/5/courses) and the later is for controlling the relationship itself (PATCH students/5/relationship/courses).

See here for more information:

http://jsonapi.org/format/upcoming/#crud-updating-to-many-re...

Re: Rules for REST API URI Design

#64

Post by Coincoin »

ryanbrunner wrote: post #40

I don't disagree with most of the rules, but it's more than a little ironic that the supporting quote at the top of the page that the article seemingly hangs off directly contradicts most of the article: > The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information. - Tim Berners-Lee By this quot…

Most compilers interprets variables name as opaque identifiers without semantic meaning. Does that mean I should not have rules to name variables?

The way I interpreted the quote is: Don't parse the URI in your program to try to gain information about a resource other than it's ID. It doesn't mean you can't put information in there to make it easier for human developers to understand.

In other words, pretty names are for humans, not machines.

Re: Rules for REST API URI Design

#65

Post by vbezhenar »

Two points that I don't understand.

1. Using dash instead of underscore as a space replacement. Underscore is a much more natural as a space replacement and dash is actually a punctuation character. An article gives the following reason: "Text viewer applications (browsers, editors, etc.) often underline URIs to provide a visual cue that they are clickable. Depending on the application’s font, the underscore (_) character can either get partially obscured or completely hidden by this underlining.". It's not convincing at all. I've never encountered this glitch.

2. The keep-it-simple rule applies here. Although your inner-grammatician will tell you it's wrong to describe a single instance of a resource using a plural, the pragmatic answer is to keep the URI format consistent and always use a plural.

But why plural and not single? English is a weird language and it has numerous exceptions for plural form. Isn't it simpler to use single form? I'm always using single form everywhere, works fine for me.

Re: Rules for REST API URI Design

#66

Post by barrkel »

rdsubhas wrote: post #46
macca321 wrote: post #43

Earlier quoted context omitted.

Yes, The article is talking about REST as in "JSON RPC over HTTP" as opposed to REST as the person who came up with it (Roy Fielding) intended. If you are worrying about URL readability you aren't doing REST.

Spot on. RESTful URLs are not to be treated like SEO URLs. But unfortunately most people don't see the difference. One example in the article is especially harmful (/students/ /courses/physics for querying). The single best slideshare I've found on REST is Teach a Dog to REST. Old but gold. https://www.slideshare.net/landlessness/teach-a-dog-to-rest (And a shameful plug - https://medium.com/@rdsubhas/pitiful-restful-…

Most web apps (outside of websites themselves, which are a kind of very simple application) aren't HATEOAS, so Roy's thesis has less purchase on their design.

Re: Rules for REST API URI Design

#67

Post by rdsubhas »

rimliu wrote: post #51
rdsubhas wrote: post #46

Earlier quoted context omitted.

Spot on. RESTful URLs are not to be treated like SEO URLs. But unfortunately most people don't see the difference. One example in the article is especially harmful (/students/ /courses/physics for querying). The single best slideshare I've found on REST is Teach a Dog to REST. Old but gold. https://www.slideshare.net/landlessness/teach-a-dog-to-rest (And a shameful plug - https://medium.com/@rdsubhas/pitiful-restful-…

> RESTful URLs are not to be treated like SEO URLs But it does not hurt to have them human-readable.

It does hurt. Examples in the article linked above.

Re: Rules for REST API URI Design

#68

Post by vmasto »

vbezhenar wrote: post #65

Two points that I don't understand. 1. Using dash instead of underscore as a space replacement. Underscore is a much more natural as a space replacement and dash is actually a punctuation character. An article gives the following reason: "Text viewer applications (browsers, editors, etc.) often underline URIs to provide a visual cue that they are clickable. Depending on the application’s font, the underscore (_) char…

Regarding your point in 2: do you store your docs in a directory called Documents or Document?

Re: Rules for REST API URI Design

#69

Post by PeterisP »

macca321 wrote: post #43
ryanbrunner wrote: post #40

I don't disagree with most of the rules, but it's more than a little ironic that the supporting quote at the top of the page that the article seemingly hangs off directly contradicts most of the article: > The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information. - Tim Berners-Lee By this quot…

Yes, The article is talking about REST as in "JSON RPC over HTTP" as opposed to REST as the person who came up with it (Roy Fielding) intended. If you are worrying about URL readability you aren't doing REST.

In most contexts what you actually need is REST as in "JSON RPC over HTTP" instead of REST as Roy Fielding intended.

So the recommendations in the article are actually valid and useful, but we'd need to come up with another name to properly distinguish which "REST" we're talking about, at least unless/until one of these usages fades into obscurity.

Re: Rules for REST API URI Design

#70

Post by tchow »

laumars wrote: post #29
tchow wrote: post #19

When doing something like `student/1245/courses` there will certainly be a scenario where you want a list of courses on their own as well. If planning ahead, does that warrant designing your route such as: `/courses` where you get a list of courses and `/courses?studentId=12345` Where you get courses scoped to a student... Or is it better to just recreate a separate route such that you have /courses AND student/2345/…

If it's an API then you could bypass the aforementioned constraints of spitting your request up by URI "directories" and instead have your query's parameters passed via form data or serialised as JSON* in the HTTP request body. URIs are easier to deal with but not _that_ much easier if you're programmatically sending the requests as one might expect to do with an API * Other data formats also exist

Adding stuff to a request body in GET is considered an antipattern
Post reply on HN