Rules for REST API URI Design • Hacker News Board

Re: Rules for REST API URI Design

#21

Post by pyre » Sun, Jun 18, 2017, 8:34 AM UTC

idkfa wrote: post #20

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

As in design a custom TCP/IP protocol for every application?

Re: Rules for REST API URI Design

#22

Post by mxstbr » Sun, Jun 18, 2017, 8:34 AM UTC

This post makes me very happy to be using GraphQL. (not trying to start another flamewar)

Rather than following arbitrary "best practices" you dig up from random articles and might or might not know or follow, GraphQL forces you to write your API a certain way.

That is not to say GraphQL is a silver bullet, it has it's own problems, but at least I can concentrate on my application and how it needs to work rather than reading more articles about how exactly to name my URLs.

Re: Rules for REST API URI Design

#23

Post by elvinyung » Sun, Jun 18, 2017, 8:44 AM UTC

Orthogonal: I wish there was a good RPC protocol for the web. REST really sucks when you're not doing CRUD (which, frankly, is way more often than expected).

Re: Rules for REST API URI Design

#24

Post by jack9 » Sun, Jun 18, 2017, 8:49 AM UTC

noisy_boy wrote: post #16

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 ?

He's trying to articulate using arbitrary semantic uri schemes (that was just a simple example) rather than HTTP verbs. Ultimately, you have to document them in your APIs anyway and the caching reasoning (along with all the others I've heard), just haven't been useful in practice.

Re: Rules for REST API URI Design

#25

Post by forgottenacc57 » Sun, Jun 18, 2017, 9:04 AM UTC

I can't help feeling a great deal of the effort that goes into API definition and maintenance is pointless and a waste of time.

Re: Rules for REST API URI Design

#26

Post by forgottenacc57 » Sun, Jun 18, 2017, 9:05 AM UTC

I can't help feeling a great deal of the effort that goes into API definition is pointless and a waste of time.

Re: Rules for REST API URI Design

#27

Post by Frizi » Sun, Jun 18, 2017, 9:15 AM UTC

Or, you know, just use GraphQL as your protocol and be done with this. Everything that's problematic in REST is clearly specified here and stays very easy to use. You can focus on real problems from now on.

Re: Rules for REST API URI Design

#28

Post by stingraycharles » Sun, Jun 18, 2017, 9:16 AM UTC

eponeponepon wrote: post #10

stingraycharles wrote: post #8

Earlier quoted context omitted.

A URI should represent a resource, regardless of its serialisation format. Serialisation really is part of the HTTP headers, and the support in there is great. Using this allows the web browser and the web server to completely negotiate an acceptable format themselves. Adding the serialisation format to the URI also creates a conflict: what would happen if you request a .json, but the web browser doesn't accept this…

The last case sounds like user error to me. You could say the same for using Accept headers - what happens if the user tells their line-drawing client to request a spreadsheet?

In the case of accept headers, you would have actual negotiation; the client sends all of the formats it accepts, and the server chooses the most suitable one. If none are available, it would return a 406 Not Acceptable.

The problem with putting another, incompatible serialisation format on top of that is that it creates conflicts, and inherently requires one to reinvent the wheel, or have a less flexible solution.

I simply fail to see what problem it solves.

Re: Rules for REST API URI Design

#29

Post by laumars » Sun, Jun 18, 2017, 9:20 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/…

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

Re: Rules for REST API URI Design

#30

Post by stingraycharles » Sun, Jun 18, 2017, 9:25 AM UTC

pyre wrote: post #21

idkfa wrote: post #20

Earlier quoted context omitted.

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

As in design a custom TCP/IP protocol for every application?

I think there are a few GraphQL enthusiasts entering this thread right now, which has its own merits, but can live perfectly next to REST.