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

51–60 of 97 posts

Re: Rules for REST API URI Design

#51

Post by rimliu »

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

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

Re: Rules for REST API URI Design

#52

Post by ruiseal »

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 think it depends on what makes sense for your problem domain. Think about what kind of HTTP methods and the associated data with each and decide accordingly.

Nesting of resources in a REST API can become problematic, for these reasons, so another option would be to get rid of the nesting and use query parameters to filter based on whatever criteria you want. This is the motivation for PostgREST [1] where the author views the shortcomings of nested API resources as similar to those of hierarchical databases. GraphQL solves this similarly, it also has a richer query language, but it's missing some of the benefits of REST like caching, etc.

[1]. https://postgrest.com/en/v4.1/intro.html

Re: Rules for REST API URI Design

#54

Post by rimliu »

stingraycharles wrote: post #8
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

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…

  > Serialisation really is part of the HTTP headers, and the
  > support in there is great.
True. But being able to get XML or JSON just by changing what you type into browser URL field is a nice and helpful feature.

  > what would happen if you request a .json, but the web
  > browser doesn't accept this format ?
And what happens when you do the same via HTTP headers?

Re: Rules for REST API URI Design

#55

Post by rimliu »

stingraycharles wrote: post #28
eponeponepon wrote: post #10

Earlier quoted context omitted.

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

  > the client sends all of the formats it accepts
And currently many clients only support JSON. As do many backend systems.

Re: Rules for REST API URI Design

#56

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

I don't know if it's helpful, but think of the server like a coworker with whom you can only interact by opening tickets on Jira or equivalent.

You choose the type, describe what you need, and immediately get back a ticket ID (that's the URL). Then you can check back to see the state of the ticket.

Re: Rules for REST API URI Design

#57

Post by pikzen »

icebraining wrote: post #50
pikzen wrote: post #49

Earlier quoted context omitted.

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

We've already established REST has crippling limitations. Introducing RPC in it makes up for those.

You can also make it a long lived connection, that waits for a proper confirmation, which means you might be waiting ten seconds. Or you can make it a fire-and-forget operation, and have a resource to check if it was properly sent. Which is back to polling. Or you can use server-sent events to have the server notify you back when it's done.

But yes, unless you explicitly need to be able to send emails from clientside, I wouldn't expose a sendmail resource, and would leave that to the server. (I say as I recently implemented a resource that allows me to post an event from client side to allow the server to send it back. :| )

Ultimately, do what works. The pure REST cargo cult is dangerous. As long as what you do is clean, maintainable and ideally idempotent, you're good.

Re: Rules for REST API URI Design

#58

Post by mkhattab »

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.

Re: Rules for REST API URI Design

#59

Post by icebraining »

pikzen wrote: post #57
icebraining wrote: post #50

Earlier quoted context omitted.

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

We've already established REST has crippling limitations. Introducing RPC in it makes up for those. You can also make it a long lived connection, that waits for a proper confirmation, which means you might be waiting ten seconds. Or you can make it a fire-and-forget operation, and have a resource to check if it was properly sent. Which is back to polling. Or you can use server-sent events to have the server notify yo…

We've already established REST has crippling limitations.

No, we haven't. I explicitly disagreed with that assertion. REST is not adequate for everything, but it doesn't have "crippling limitations". It's pretty good for its intended use.

You can also make it a long lived connection, that waits for a proper confirmation, which means you might be waiting ten seconds.

You can't rely on the connection lasting that long. REST's design was a major sucess on the Internet in part because it naturally dealt with the connectivity limitations.

Or you can make it a fire-and-forget operation, and have a resource to check if it was properly sent.

Yes. That's what REST means. That's my point!

Or you can use server-sent events to have the server notify you back when it's done.

You still have to create an unique ID for the operation, so that the client can tell what is done. Having an URL as that ID is barely any effort.

Ultimately, do what works. The pure REST cargo cult is dangerous. As long as what you do is clean, maintainable and ideally idempotent, you're good.

There's nothing clean and maintainable about having ad-hoc mechanisms that break the overall functioning of the API. If you're using a paradigm, be that REST, RPC, or anything else, you should have a major reason to break it.

Re: Rules for REST API URI Design

#60

Post by pikzen »

icebraining wrote: post #59
pikzen wrote: post #57

Earlier quoted context omitted.

We've already established REST has crippling limitations. Introducing RPC in it makes up for those. You can also make it a long lived connection, that waits for a proper confirmation, which means you might be waiting ten seconds. Or you can make it a fire-and-forget operation, and have a resource to check if it was properly sent. Which is back to polling. Or you can use server-sent events to have the server notify yo…

We've already established REST has crippling limitations. No, we haven't. I explicitly disagreed with that assertion. REST is not adequate for everything, but it doesn't have "crippling limitations". It's pretty good for its intended use. You can also make it a long lived connection, that waits for a proper confirmation, which means you might be waiting ten seconds. You can't rely on the connection lasting that long.…

... Then make an endpoint where you can get a task's status through its ID (your post to sendmail would then return a task ID), and poll repeatedly until it's marked as done, wasting bandwidth, your architecture, your choices ¯\_(ツ)_/¯

Or you can let the server notify you when it's done, and carry on with your work. As a bonus, most clients able to receive SSE already include automatic reconnection to the feed if it ever gets cut.

Post reply on HN