Rules for REST API URI Design • Hacker News Board

Re: Rules for REST API URI Design

#11

Post by andreareina » Sun, Jun 18, 2017, 7:56 AM UTC

tudorconstantin wrote: post #5

I love the REST principles. The RESTful ideas framework (I call it like this because I lack a better name for them) helped me organize my applications in a much more consistent manner. I wonder if a URI like http://api.college.com/students/3248234/courses/physics/stud... would actually make sense to get a list of all the students who take the same physics course that student 3248234 takes. If yes, is there a web fram…

If you're using the url as a hierarchical representation, it wouldn't make sense. What happens if you ask for a circular reference like /students/3248234/courses/physics/students/3248234? You can either query the student to get the course's uri, then access /courses//students.

Re: Rules for REST API URI Design

#12

Post by hamandcheese » Sun, Jun 18, 2017, 7:58 AM UTC

Overall this seems like a clickbaity list of practices that have been well established for a while now. REST is easy when you're just doing CRUD. It's once you have actions besides "update" that things start to get a bit more interesting.

Re: Rules for REST API URI Design

#13

Post by eponeponepon » Sun, Jun 18, 2017, 7:59 AM UTC

teddyh wrote: post #9

Nice rules, except for #7. Class names are singular, as are most SQL tables in modern SQL. I think this pattern should be followed also in URL design, since it’s more common to refer to a single at /person/327 than the list of all people at /person. However, everyone designing an API should be aware that the REST principles really don’t work very well without HATEOAS, and HATEOAS does not require any “designed” URLs,…

I actually think the singular/plural question isn't too important - the key thing is that it's consistent across the whole API.

Re: Rules for REST API URI Design

#14

Post by zaidf » Sun, Jun 18, 2017, 8:00 AM UTC

On a related topic, I hear the best practice is to make use of HTTP methods like PUT and DELETE. Am I in a tiny minority that wishes we could use verbs in URIs, ie http://api.blah.com/student/32/delete instead of relying on the DELETE http method to communicate that point?

Re: Rules for REST API URI Design

#15

Post by badminton1 » Sun, Jun 18, 2017, 8:03 AM UTC

URI normalization takes care of trailing slashes (RFC3986).

If you are parsing URLs yourself try to stick to the WHATWG URL standard (https://url.spec.whatwg.org/).

Re: Rules for REST API URI Design

#16

Post by noisy_boy » Sun, Jun 18, 2017, 8:04 AM UTC

zaidf wrote: post #14

On a related topic, I hear the best practice is to make use of HTTP methods like PUT and DELETE. Am I in a tiny minority that wishes we could use verbs in URIs, ie http://api.blah.com/student/32/delete instead of relying on the DELETE http method to communicate that point?

Wouldn't that place "delete" at the same level as, e.g., "courses" i.e. http://api.blah.com/student/32/courses?

Re: Rules for REST API URI Design

#17

Post by idkfa » Sun, Jun 18, 2017, 8:07 AM UTC

hamandcheese wrote: post #12

Overall this seems like a clickbaity list of practices that have been well established for a while now. REST is easy when you're just doing CRUD. It's once you have actions besides "update" that things start to get a bit more interesting.

when things start to get interesting, it's better to switch to JSON-RPC

Re: Rules for REST API URI Design

#18

Post by tomstuart » Sun, Jun 18, 2017, 8:09 AM UTC

zaidf wrote: post #14

On a related topic, I hear the best practice is to make use of HTTP methods like PUT and DELETE. Am I in a tiny minority that wishes we could use verbs in URIs, ie http://api.blah.com/student/32/delete instead of relying on the DELETE http method to communicate that point?

Yes, because request methods provide a uniform way of communicating meaningful information to HTTP infrastructure like caches. If a request uses the DELETE method then a cache in the middle can know something about the meaning of that request (e.g. it's idempotent) and change its behaviour accordingly. If that information lives only in the URI then there's no way for a cache to understand its significance.

Re: Rules for REST API URI Design

#19

Post by tchow » Sun, Jun 18, 2017, 8:14 AM UTC

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

Im concerned that the latter results in duplication of code and possibly more confusion (ie not clear if the API require POST to /courses or /student/12345/courses to create a course for a student ) while the former results may cause (lack of) caching problems.

Suggestions?

Re: Rules for REST API URI Design

#20

Post by idkfa » Sun, Jun 18, 2017, 8:19 AM UTC

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

just drop this REST hype altogether and use adequate protocols for communication