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

41–50 of 97 posts

Re: Rules for REST API URI Design

#41

Post by kuon »

TrickyRick wrote: post #3

I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI

I agree. Also it might be more convenient when doing get request. Imagine an API generating images like /cat/300x300.jpg the ability to switch to .png is really handy. Of course you could do /cat/300x300/png and don't use extensions.

I think it's up to particular use cases.

Re: Rules for REST API URI Design

#42

Post by ryanbrunner »

mxstbr wrote: post #22

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…

GraphQL is just another set of "arbitrary" best practices. If you're looking for a ambiguity-free prescriptive approach to implementing a REST API, there's plenty out there (MS, Google, and tons of other companies have very prescriptive approaches to building REST APIs), and some frameworks like Rails push you strongly in one direction (for example, most of the rules of this article are something that isn't a decision you need to make in Rails)

Re: Rules for REST API URI Design

#43

Post by macca321 »

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.

Re: Rules for REST API URI Design

#44

Post by eponeponepon »

badminton1 wrote: post #15

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

I hadn't seen this before - it's horrifying.

Right up the top it declares that its intent is to _obsolete_ the existing RFCs - and then just breezily drops this in: "As the editors learn more about the subject matter the goals might increase in scope somewhat."

Honestly, I'm gobsmacked. I really hope nobody's taking this document seriously.

Re: Rules for REST API URI Design

#45

Post by tshaddox »

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…

Ruby on Rails easily supports arbitrarily nested resourceful routes, but they strongly (and wisely, in my experience) advise against precisely this type of deep nesting.

http://guides.rubyonrails.org/routing.html#nested-resources

http://weblog.jamisbuck.org/2007/2/5/nesting-resources

Re: Rules for REST API URI Design

#46

Post by rdsubhas »

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.

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-urls-5d576ffccb...)

Re: Rules for REST API URI Design

#47

Post by icebraining »

matrixagent wrote: post #38
icebraining wrote: post #35

Earlier quoted context omitted.

I disagree, it's fairly simple, people only find it hard because they're thinking in RPC terms - in commands instead of resources. An action is simply a new resource you create. You don't send_emails(), you create a new email sending resource, which has its own URL you can check in later (giving you built-in resilience to network cuts and other problems). I'm yet to find an action you can't easily model with resource…

Could you maybe elaborate a bit more with your send email example? We've been struggling a bit with API design and exactly this kind of thinking everything as a resource. I'm still having a hard time to imagine exactly how "a new email sending resource" would/should look like. having something like /api/sendmail/confirmation would trigger my confirmation mail sending method internally, which clearly is RPC thinking.…

What exactly are you trying to model? What type of emails are those?

Generally, trying to treat the server as a dumb API doesn't work well. If your client is the one who knows that something was confirmed, it should tell the server that, and let it worry about sending whatever emails it wants.

So you'd just PUT your resource with state=confirmed, and let the server take care of any side effects that might trigger.

On the other hand, if it's something like a mass email created by the user, then the client should POST to create a new "mass mailing resource", then it'd PUT all the changes made by the client, and finally PUT its state to "ready to send" so that the server can do so.

Re: Rules for REST API URI Design

#48

Post by MuppetMaster42 »

Frizi wrote: post #27

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.

We've recently started our transition from full rest to graphql. It's actually magical how much easier it is to do everything.

We've used join-monster to handle the sql generation so it's been a breeze to get everything up and running.

Its surprising how fast it is too. We used to use sequelize glasses an orm, but we were getting 4-500ms r times on simple requests. Now for the most part we get sub 100ms responses on complex queries.

Re: Rules for REST API URI Design

#49

Post by pikzen »

matrixagent wrote: post #38
icebraining wrote: post #35

Earlier quoted context omitted.

I disagree, it's fairly simple, people only find it hard because they're thinking in RPC terms - in commands instead of resources. An action is simply a new resource you create. You don't send_emails(), you create a new email sending resource, which has its own URL you can check in later (giving you built-in resilience to network cuts and other problems). I'm yet to find an action you can't easily model with resource…

Could you maybe elaborate a bit more with your send email example? We've been struggling a bit with API design and exactly this kind of thinking everything as a resource. I'm still having a hard time to imagine exactly how "a new email sending resource" would/should look like. having something like /api/sendmail/confirmation would trigger my confirmation mail sending method internally, which clearly is RPC thinking.…

/api/sendmail, data passed in POST as JSON. POSTing doesn't have to be uniquely identified.

Re: Rules for REST API URI Design

#50

Post by icebraining »

pikzen wrote: post #49
matrixagent wrote: post #38

Earlier quoted context omitted.

Could you maybe elaborate a bit more with your send email example? We've been struggling a bit with API design and exactly this kind of thinking everything as a resource. I'm still having a hard time to imagine exactly how "a new email sending resource" would/should look like. having something like /api/sendmail/confirmation would trigger my confirmation mail sending method internally, which clearly is RPC thinking.…

/api/sendmail, data passed in POST as JSON. POSTing doesn't have to be uniquely identified.

Yes, but that's RPC thinking. What if the queue is backlogged? What happens if the email doesn't get delivered? If your client asks for the email to be sent, it should deal with it during its lifecycle.

In my opinion, one shouldn't have a /sendmail API at all, the server should deal with that, but if one really needs the client to do that, then /sendmail should at least return a URL that represent the email being sent, so that the client can keep track of it even after the connection is lost or the device is rebooted.

Post reply on HN