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

81–90 of 97 posts

Re: Rules for REST API URI Design

#81

Post by stingraycharles »

PeterisP wrote: post #75
stingraycharles wrote: post #28

Earlier quoted context omitted.

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

In practical applications, I'd want it to be the opposite way around - the server will be coded to support multiple formats since it serves many clients and many types of clients, but any particular client explicitly targeting that server will likely implement just a single format for exchanging data with your app. So you'd want the server to send all the formats it can provide (i.e. as a list of different resource U…

> So you'd want the server to send all the formats it can provide (i.e. as a list of different resource URLs) and the client chooses whatever it prefers, entirely the other way around as you describe.

What is the advantage of that, compared to having normal Accept: encoding ? Please note that in the negotiation phase, a server uses the format that the client actually prefers; it's able to tell the server these things (e.g. "if you have json, give me that, otherwise I'll take XML).

Your solution requires an additional round-trip for this same negotiation.

Re: Rules for REST API URI Design

#82

Post by stingraycharles »

jmull wrote: post #78
stingraycharles wrote: post #28

Earlier quoted context omitted.

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

It doesn't have to be done in a bad/incompatible/new way. Here's what I did for an API I worked on recently supports JSON and XML: The general route for a resource is an endpoint that can serve both application/json and application/xml, the ".json" route identifies an endpoint that will serve only application/json and ".xml" identifies an endpoint that will serve application/xml. None of that conflicts with normal co…

> The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing.

First of all, these things are supported by HTTP headers; you can send "Accept: application/json;q=0.9, application/xml;q=0.1" and the server will always send JSON if it supports it.

The problem you mention is fair, but REST APIs are designed for consumption by computers, not humans. So while it is a fair point, it is explicitly a non-goal for REST APIs.

Re: Rules for REST API URI Design

#83

Post by [deleted] »

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…

[deleted]

Re: Rules for REST API URI Design

#84

Post by badminton1 »

eponeponepon wrote: post #44
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.

It may be bad but unfortunately it's the closest to a serious/workable standard nowadays regarding URLs.

Re: Rules for REST API URI Design

#85

Post by bulatb »

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

Any RPC-style endpoint can be represented in REST by exposing the resulting event as a first-class object you can read and write.

Turn your verb into a noun: instead of "move $10 from Alice's to Bob's account", your clients will ask to "record a transfer of $10 from Alice to Bob". A transfer is a type of record the client creates with a POST, not a function call that results in money being moved. Creating it records the client's intended result; how and when to implement the actual transfer of money is not the client's concern. If Alice wants to check if Bob received the money, for example, she can GET /transfers/ and look at the fields.

For emails sent to users, I'm not sure what you'd call it. The simple verb-the-noun rule would make it a "send", but sometimes you need something better. Maybe a "thread" or "communication."

This would be a natural API design for CQRS/ES, but you could also use it (with adjustments, maybe) to present a RESTful interface to something that, behind the scenes, just moves the money right away and never thinks about transactions as an entity.

The key to modeling this way is in the name: REpresentational State Transfer, meaning clients send a snapshot of the current or desired state of a resource instead of calling functions that change it. And sometimes, to make it make sense, you have to invent a new kind of resource.

Re: Rules for REST API URI Design

#86

Post by concede_pluto »

eponeponepon wrote: post #44
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.

All you need to know about WHATWG is that the monstrosity they're billing as "HTML" has neither version numbers nor a formal grammar.

Re: Rules for REST API URI Design

#87

Post by jmull »

stingraycharles wrote: post #82
jmull wrote: post #78

Earlier quoted context omitted.

It doesn't have to be done in a bad/incompatible/new way. Here's what I did for an API I worked on recently supports JSON and XML: The general route for a resource is an endpoint that can serve both application/json and application/xml, the ".json" route identifies an endpoint that will serve only application/json and ".xml" identifies an endpoint that will serve application/xml. None of that conflicts with normal co…

> The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing. First of all, these things are supported by HTTP headers; you can send "Accept: application/json;q=0.9, application/xml;q=0.1" and the server…

On your second paragraph... I don't think you can generally state that REST APIs don't need to be developable, supportable, teachable/learnable. Ad hoc requests support these things in useful ways that scripted requests do not. That makes it a fair goal for REST APIs.

On your first paragraph, sorry I don't understand your point. I showed how this can be done in a way that is fully consistent with standard content negotiation, like your example.

Re: Rules for REST API URI Design

#88

Post by laumars »

tchow wrote: post #70
laumars wrote: post #29

Earlier quoted context omitted.

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

If your APIs are login sensitive then you'd want your APIs to be POST requests anyway.

Re: Rules for REST API URI Design

#89

Post by lioeters »

elvinyung wrote: post #23

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

I also prefer RPC-style interfaces, and tend to use it internally - i.e., not exposed as public API, since REST is usually the expected standard. In one application, I was able to use the same group of commands for both AJAX and WebSockets, which just mapped to a folder of functions. It was a pleasure to forget the boundary between client and server, and treat the server as just an asynchronous function call away. I suppose there's nothing stopping me from using a similar structure for external parties to consume the data, it's just that there's no established standard/protocol for how to expose and document such APIs..?

Re: Rules for REST API URI Design

#90

Post by hamandcheese »

icebraining wrote: post #35
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.

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…

Creating a new resource for everything sounds very tedious though. A simple example might be upvoting. I think taking a step away from REST and making a /upvote action makes for an easier to consume API.

To be a bit more abstract, consider complex state transitions on a resource. In some cases it can make a lot more sense for a client to say "transition to this state" without explicit knowledge of how to do so. To do this restfuly you could maybe update a virtual "state" field to the desired state, but to me that can feel very unnatural.

Post reply on HN