Live data from Hacker News

Designing a Pragmatic RESTful API

vinaysahni.com

131–139 of 139 posts

Re: Designing a Pragmatic RESTful API

#131
post #36

Something to consider, the author advocates json responses across the board, which is pretty good advice, however, it's incompatible with `204 No Content` responses (also recommended). If you're building a client that connects to an API that could potentially return a `204 No Content` response, you can't assume that there will be json in the body and automatically parse the response.

I don't see the problem here. You get a 204, you don't expect content. If your consumer hits a URL, ignores status codes, and expects content, You're Doing It Wrong.

To me, it looks like the HTTP equivalent of a C function that returns NULL.

Re: Designing a Pragmatic RESTful API

#132

Earlier quoted context omitted.

It's why I've come to prefer the term "RESTish". It probably still isn't enough to mollify hard-core purists but indicates that, e.g. the user knows versioning ought to be in the accept header rather than the URL, but also that hardly anyone either creating or using web APIs cares.

I have always considered "RESTful" to be analagous to your "RESTish" meaning. If I am 100% REST then I would say "I have a REST API". If, like most companies, I am not following all the REST conventions then I would say "RESTful" api. The moaning about "RESTful has been hijacked by people who don't know REST" by the REST purists always struck me as strange when they could have made that simple distinction.

The suffix -ful literally means "as much as will fill", e.g. spoonful, and usually takes the broader meaning "characterized by", e.g. careful. As such, I've always regarded "RESTful" as a full REST implementation, and it seems most other people who have an opinion on the matter do too.

I borrowed RESTish from Dan Savage's concept of "monogamish", meaning a relationship that conforms generally but not rigidly and precisely to the norms of monogamy. As such, a RESTish API conforms generally but not rigidly and precisely to the norms of REST.

Re: Designing a Pragmatic RESTful API

#133

Earlier quoted context omitted.

> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don'…

> It should generally work for anything if you model it right. No, this is not true. Each constraint of REST comes with drawbacks, and if you can't afford those drawbacks, you can't do it RESTfully. Fielding's thesis is very upfront about this. The biggie: latency. If you need sub-10ms responses, REST is the wrong way to go about modelling your problem domain. The second: client-server. If you want the server to init…

First, I think that you misunderstood what I meant by "anything" -- I meant any logical model of what an API does, which seemed in context to be what the post I was responding to was asking about. I wasn't saying "anything" in the sense of any combination of performance requirements.

That being said, I'm not convinced that your particular objections, aside from responding to "anything" in a different sense than intended in context, are really accurate.

> The biggie: latency. If you need sub-10ms responses, REST is the wrong way to go about modelling your problem domain.

HTTP might be problematic here, but I don't see why REST is problematic. (REST doesn't rely on HTTP -- in fact, HTTP is itself a REST-based system -- and can be implemented over protocols with different performance characteristics.)

Its obviously a problem for every request to navigate from the API root if you have tight latency constraints, but there is nothing unRESTful about having a client cache the locations of the key resources it is interested in after the first access. In fact, reducing latency by encouraging cacheability is an explicitly-cited motivation for REST.

> The second: client-server. If you want the server to initiate behavior on the client, REST is the wrong way to go.

If you want system A to initiate a behavior on system B, then in the context of REST with regard to the behavior at issue, A is a client consuming an API and B is a server providing an API. If it is necessary for other reasons for A to be an HTTP server and B to the HTTP client, then you obviously aren't going to be doing typical REST-over-HTTP to implement the API that A is consuming and B is providing. But there is no reason that you can't use a REST architecture for the API. (OTOH, since, in simple cases, the API implementation will likely be being provided as Code-on-Demand to B by A, there's may not be a lot of reason to use REST, but it could help reduce coupling between different components on A.)

Re: Designing a Pragmatic RESTful API

#134

Earlier quoted context omitted.

It's why I've come to prefer the term "RESTish". It probably still isn't enough to mollify hard-core purists but indicates that, e.g. the user knows versioning ought to be in the accept header rather than the URL, but also that hardly anyone either creating or using web APIs cares.

I have always considered "RESTful" to be analagous to your "RESTish" meaning. If I am 100% REST then I would say "I have a REST API". If, like most companies, I am not following all the REST conventions then I would say "RESTful" api. The moaning about "RESTful has been hijacked by people who don't know REST" by the REST purists always struck me as strange when they could have made that simple distinction.

> If I am 100% REST then I would say "I have a REST API". If, like most companies, I am not following all the REST conventions then I would say "RESTful" api.

If you aren't following REST conventions, its probably better to say "HTTP API" and not make any claims at all related to REST (except, perhaps, negative ones like "non-REST".)

Re: Designing a Pragmatic RESTful API

#135

Earlier quoted context omitted.

> It should generally work for anything if you model it right. No, this is not true. Each constraint of REST comes with drawbacks, and if you can't afford those drawbacks, you can't do it RESTfully. Fielding's thesis is very upfront about this. The biggie: latency. If you need sub-10ms responses, REST is the wrong way to go about modelling your problem domain. The second: client-server. If you want the server to init…

First, I think that you misunderstood what I meant by "anything" -- I meant any logical model of what an API does, which seemed in context to be what the post I was responding to was asking about. I wasn't saying "anything" in the sense of any combination of performance requirements. That being said, I'm not convinced that your particular objections, aside from responding to "anything" in a different sense than inten…

> I meant any logical model of what an API does,

Gotcha. You're right that I got this wrong, but I think my objection still stands; a peer-to-peer interaction model is still not RESTful.

> Its obviously a problem for every request to navigate from the API root if you have tight latency constraints,

Even in truly RESTful systems, 'every request' wouldn't navigate from the root; the first interaction starts there, but it's not like you keep going back to the root every single time you want to do anything.

> In fact, reducing latency by encouraging cacheability is an explicitly-cited motivation for REST.

Absolutely. I was thinking of the 'layered system' constraint. From http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... :

> The primary disadvantage of layered systems is that they add overhead and latency to the processing of data, reducing user-perceived performance.

You are right that caching helps balance this out, but not everything can be cached; for example, a first-person shooter game would be hard to cache.

> A is a client consuming an API and B is a server providing an API.

Even if it's 'oh they're just two different APIs working together', it's not a singular API, which is what we're talking about here.

Re: Designing a Pragmatic RESTful API

#136

Earlier quoted context omitted.

First, I think that you misunderstood what I meant by "anything" -- I meant any logical model of what an API does, which seemed in context to be what the post I was responding to was asking about. I wasn't saying "anything" in the sense of any combination of performance requirements. That being said, I'm not convinced that your particular objections, aside from responding to "anything" in a different sense than inten…

> I meant any logical model of what an API does, Gotcha. You're right that I got this wrong, but I think my objection still stands; a peer-to-peer interaction model is still not RESTful. > Its obviously a problem for every request to navigate from the API root if you have tight latency constraints, Even in truly RESTful systems, 'every request' wouldn't navigate from the root; the first interaction starts there, but…

On latency and the layered system constraint you have a point.

> Even if it's 'oh they're just two different APIs working together', it's not a singular API, which is what we're talking about here.

I thought we were talking about the utility of REST architecture for the API(s) involved. Obviously, if you have requirements which require two different APIs where the consumers of one API are the providers of the other API, then regardless of architecture, it won't be one API, but that's orthogonal to the architecture appropriate to either or both APIs.

Re: Designing a Pragmatic RESTful API

#137

Earlier quoted context omitted.

First, I think that you misunderstood what I meant by "anything" -- I meant any logical model of what an API does, which seemed in context to be what the post I was responding to was asking about. I wasn't saying "anything" in the sense of any combination of performance requirements. That being said, I'm not convinced that your particular objections, aside from responding to "anything" in a different sense than inten…

> I meant any logical model of what an API does, Gotcha. You're right that I got this wrong, but I think my objection still stands; a peer-to-peer interaction model is still not RESTful. > Its obviously a problem for every request to navigate from the API root if you have tight latency constraints, Even in truly RESTful systems, 'every request' wouldn't navigate from the root; the first interaction starts there, but…

[deleted]

Re: Designing a Pragmatic RESTful API

#138
This is a great article, and although it may raise the ire of some of the REST purists out there, I completely agree with the pragmatic approach. It prompted me to finally publish some of my thoughts on API design that complement the more technical ones in the article:

https://news.ycombinator.com/item?id=5831253

Re: Designing a Pragmatic RESTful API

#139
post #36

Something to consider, the author advocates json responses across the board, which is pretty good advice, however, it's incompatible with `204 No Content` responses (also recommended). If you're building a client that connects to an API that could potentially return a `204 No Content` response, you can't assume that there will be json in the body and automatically parse the response.

I don't see the problem here. You get a 204, you don't expect content. If your consumer hits a URL, ignores status codes, and expects content, You're Doing It Wrong. To me, it looks like the HTTP equivalent of a C function that returns NULL.

Agreed. Just throwing it out there since I've encountered it before, more than once, where others assume there will always be a response, regardless of status code.
Post reply on HN