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

91–97 of 97 posts

Re: Rules for REST API URI Design

#91

Post by icebraining »

hamandcheese wrote: post #90
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…

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…

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.

How are you imagining the REST equivalent? Because that's also what I'd do: create a /post//upvote URL that the client would just have to POST to. That's perfectly RESTful, you're creating a new upvote, you don't have to care about the resulting resource if you don't need to manipulate it further.

To do this restfuly you could maybe update a virtual "state" field to the desired state, but to me that can feel very unnatural.

Why?

Re: Rules for REST API URI Design

#93

Post by laumars »

mehh wrote: post #92
laumars wrote: post #88

Earlier quoted context omitted.

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

Wat?

If your REST APIs do updates or retrieve sensitive information then odds are you'll have some kind of authentication method, possibly with session cookies or whitelisted IPs. Allowing sensitive APIs to be sent via GET means that you open yourself up to a couple of easy vectors of attack. eg a malicious webpage with a " rel="nofollow">http://example.com"> tag using the API end point as the src URI. This means the target person opening the page will send the API request as themselves, using their IP and cookies. Granted the API wont return an image so the "image" will fail to render but that doesn't matter as the API will still execute successfully. However if your APIs only accept POST requests then you mitigate this particularly attack.

It's pretty common advice to recommend any APIs that require user authentication to be sent via POST. In fact it's one of the first things pen testers will check for and you'd also fail PCI DSS vulnerability scans for exposing APIs via GET as well.

Disclaimer: I've works on multiple projects that have been pen tested, been audited by the UK Gambling Commission and/or had to adhere to PCI Data Security Standards.

Re: Rules for REST API URI Design

#94

Post by dozzie »

PeterisP wrote: post #69
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.

In most contexts what you actually need is REST as in "JSON RPC over HTTP" instead of REST as Roy Fielding intended. So the recommendations in the article are actually valid and useful, but we'd need to come up with another name to properly distinguish which "REST" we're talking about, at least unless/until one of these usages fades into obscurity.

> we'd need to come up with another name to properly distinguish which "REST" we're talking about

"Underspecified, broken half-implementation of RPC" is quite precise, but most of the programmers don't like being reminded that they implement a brain-dead idea.

I never understood why people don't use one of the already-defined RPC protocols, rolling instead their own versions (each different) that don't even signal errors properly.

Re: Rules for REST API URI Design

#95

Post by mxstbr »

ryanbrunner wrote: post #42
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 decisio…

Sure, but at least these arbitrary best practices are enforced at a framework level. I can't not adhere to the GraphQL way of doing things!

Re: Rules for REST API URI Design

#96

Post by macca321 »

Coincoin wrote: post #64
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…

Most compilers interprets variables name as opaque identifiers without semantic meaning. Does that mean I should not have rules to name variables? The way I interpreted the quote is: Don't parse the URI in your program to try to gain information about a resource other than it's ID. It doesn't mean you can't put information in there to make it easier for human developers to understand. In other words, pretty names are…

And in a 'true' REST API the pretty name for humans should be in the link text, not the href

Re: Rules for REST API URI Design

#97

Post by OJFord »

laumars wrote: post #93
mehh wrote: post #92

Earlier quoted context omitted.

Wat?

If your REST APIs do updates or retrieve sensitive information then odds are you'll have some kind of authentication method, possibly with session cookies or whitelisted IPs. Allowing sensitive APIs to be sent via GET means that you open yourself up to a couple of easy vectors of attack. eg a malicious webpage with a " rel="nofollow">http://example.com"> tag using the API end point as the src URI. This means the targ…

> I've works on multiple projects that have been pen tested, been audited by the UK Gambling Commission and/or had to adhere to PCI Data Security Standards.

Why do you want to 'disclaim' that? Assuming it's true, you might have meant 'disclosure', but I think what you really mean is much closer to 'source' - i.e. 'why I know this'.

Post reply on HN