
Designing a Pragmatic RESTful API - veesahni
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api?hn
======
buro9
We've built a first version of an API that we have in testing at the moment,
and it follows a lot of the things laid out in an ebook✝ and in the linked
article.

The epiphany we had was that whilst machines do access the API, the developer
is always the customer and user. Everything we do should help the developer,
and if we have to break rules to help them... then largely we should.

I've built a couple of very pure REST APIs in the past, but had a lot of
developers pushing back and demanding something simpler. To not use media
types so precisely, to be more accepting of what data is sent, to provide
meta-data along with the resource (most seem to prefer an envelope), to prefer
composite resources over very decoupled interfaces, etc.

This time, I haven't even tried to build a pure REST API. This time I've just
mixed together the bits that developers I've spoken to liked and prefer.
Adjusting as I went depending on how it was received.

<http://microcosm-cc.github.io/>

That's the docs for it, and we get the arguments out the way right at the
beginning. All we're trying to do is build an API that helps developers get
their task done. We're not done, and I know it's not pure anything... but the
feedback we're getting is far more positive than any pure REST API I've ever
built.

✝ If you are willing to give out a fake email address then this free eBook is
a great resource and has a lot of sane information presented clearly:
<http://pages.apigee.com/web-api-design-ebook.html>

~~~
h2s

        The epiphany we had was that whilst machines do access
        the API, the developer is always the customer and user.
        Everything we do should help the developer, and if we
        have to break rules to help them... then largely we
        should.
    
    

Thank you, this articulates my disagreement with the idea of hashing all URLs
so that client developers are forced to follow links returned by the API
instead of generating their own URLs

[http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-
ha...](http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-
urls/)

~~~
just2n
There's nothing really wrong with RPC-like APIs. They're often much simpler to
use in modern web development, for developers with access to documentation.

Hyperlinking has a few benefits, the biggest being discoverability without the
need for browsing some documentation that explains how to build URLs, but it's
not always the best possible solution for every application -- and it
typically leads to chatty applications.

The only thing that bothers me, though, is when these RPC APIs are called
"RESTful" just because they use HTTP verbs correctly.

~~~
sopooneo
This speaks to something that has baffled me for a long time. If we have to
bend/break the rules of REST to make things usable in the real world (and I
believe we do), why have REST as an ideal in the first place?

Why work halfway towards A, when we could define a more realistic B and
implement it fully? We spend too much time justifying which parts of the holy
book to ignore.

~~~
steveklabnik
You have different objectives than a purely RESTful system does. If you had
REST's objectives in mind, then the architectural constraints would be
sensible.

~~~
sopooneo
But who has truly RESTful objectives in mind? Are there any widely used REST
APIs that truly adhere? I acknowledge that there may be. It's just the ones I
come across always make significant concessions. Sometimes people tell me that
"the web as a whole" or RSS are examples, but those seem too fundamentally
different from any API I might create.

~~~
steveklabnik
The GitHub API is pretty damn close these days, and I can tell you that
there's a very big company you've heard of with a two-digit person team
working on a HAL-based hypermedia API right now. Twilio has been pretty good
too.

There are lots of private APIs that operate this way; for example, much of
Comcast's internal stuff is pure, hypermedia driven REST. But it's not open
source, so you don't hear about it.

A YC-funded company, Balanced Payments, does an excellent job as well.

> those seem too fundamentally different from any API I might create.

Right! That's because you're primarily thinking of RPC styles, so of course it
will seem foreign. Try this sentence on for size, from a different time
period:

"But who has truly object oriented objectives in mind? Some people tell me
that Smalltalk or C++ are examples, but those seem too fundamentally different
from any code I might write."

That's not to say RPC is a bad thing: often times, it's just fine. But if you
have the problems REST is designed to solve, REST will solve them much better.

------
peterwwillis
This is a well-written and informative article, kudos.

That said, it reminds me how fucking overcomplicated REST HTTP API is for 99%
of uses. As an API user, all I want is to call a function on a server, pass it
some arguments and get a result. I want it to be dead simple, and REST is
probably the opposite of that.

Finally, it also occurs to me that most API calls may call one function which
returns lots of data that I don't need. Specifying the data types and field
names I want in the query would simplify parsing and potentially reduce
bandwidth use (if you've ever seen an API call that returns a user's profile
when all you wanted was their last login timestamp, you know what I mean).
_edit_ Whoops, didn't see he mentioned the field limiter... why don't more
people do that?

~~~
icebraining
REST only looks complicated because you're seeing it with RPC goggles. In
REST, you don't call functions, you just ask for documents and send documents
to the server(s). There's nothing particularly complicated in it, it's just a
different approach.

That said, this article isn't particularly faithful to REST.

~~~
vyrotek
Sure, but peterwwillis was likely making the point that REST sometimes just
gets in the way. REST itself is not complicated, but trying to make it work
where it shouldn't can complicate what you're trying to do. Not all APIs can
be modeled well with the "resource" or "document" concept. A lot of times all
you really want is to ping an endpoint and get/post some data.

~~~
bbq
Maybe HTTP is simply missing the INVOKE verb for executable documents.

~~~
icebraining
If you want to retrieve some data based on some parameters, you can just GET
it and pass some query strings. You shouldn't need to care if the data comes
from an executable file (which is usually does anyway) or someone typing it in
on a terminal.

------
_pmf_
RESTful: almost correct usage of HTTP verbs to implement something that has
nothing to do with REST. But it sure sounds nice.

~~~
ExpiredLink
The obligatory "you're doing it wrong" comment following virtually all REST
articles.

~~~
johns
Once people stop calling it the wrong thing, the discussion can be about
something else.

I also hate this nitpicking, but it's clearly not going away so you're better
off not inviting it by using the term incorrectly.

~~~
RyanMcGreal
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.

~~~
rurounijones
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.

~~~
RyanMcGreal
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.

------
memset
Question: in all discussion about API design, the hairiest to me is always
authentication.

The article recommends SSL, but the internet says that "SSL is slow." Is there
a guide to using SSL correctly, and techniques for making this more efficient?
An SSL primer?

It also recommends using oauth. There are hundreds of libraries for consuming
oauth APIs. What exists (I'm a Python+Flask guy, but really any help would be
great) for _implementing_ oauth authentication for my own API?

~~~
buro9
SSL is not slow.

Grab the latest version of Nginx, turn on SPDY, enable SSL session cache.

You must _always_ serve your API over SSL, as auth information is going to be
in headers or the querystring and both would be readable by a MITM if you do
not use SSL.

Nginx 1.4 statements to pay attention to (sample config):

    
    
        ssl                       on;
        ssl_certificate           /etc/ssl/domain.crt;
        ssl_certificate_key       /etc/ssl/domain.key;
        ssl_session_cache         shared:SSL:10m;
        ssl_session_timeout       10m;
        ssl_ciphers               RC4:HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;
        ssl_stapling              on;
        spdy_headers_comp         1;
    

If you're not using Nginx, why not? Just use it as a reverse proxy and drop it
in front of whatever you are using.

~~~
T-hawk
While we're dispelling SSL myths, let me add the reminder that SSL does
encrypt the URL and querystring and HTTP headers. It doesn't look like it in
browsers because they still show the URL cleartext onscreen, but over the wire
all of that is indeed inside the encryption envelope. Only the destination IP
address isn't encrypted.

~~~
buro9
And whilst we're still here... SNI and SSL.

Thanks to Internet Explorer, and the early versions of the stock browser on
Android, you will need a unique IPv4 address for your SSL endpoint.

You cannot safely serve multiple SSL sites on the same IP.✝

Basically: The hostname is also encrypted, so the SSL requests on some
browsers require a unique IPv4 address. Your provider will give you one if you
say the magic word "SSL" to them.

✝There are ways for most browsers, but not for IE and early Android browsers.
Thankfully mobile device churn will cure us of the Android issue, but the
affected IE versions will take longer to die.

~~~
diminoten
Huh, TIL. What was the reasoning behind this?

~~~
veesahni
When client connects to server, first it does the SSL handshake. Then it sends
HTTP headers.

As a result, SSL really has nothing to do with HTTP and could be used to wrap
other protocols. Check out stunnel ( <https://www.stunnel.org/index.html> )
which can be used to arbitrarily encrypt communications for any TCP based
protocol

~~~
mcguire
And one of the first parts of the SSL handshake is for the server to send the
certificate to the client, so the server has to know which certificate to send
based only on the IP address that the client is connecting to. The client then
verifies that the certificate matches the host name it's trying to connect to.
_Then_ it sends the Host: header with the request.

It's a strict layering: TCP - SSL ("Secure Socket Layer", right?) - HTTP

There are two (and a half) ways of using a SSL certificate for multiple
hostnames on the same IP address / interface: SNI (Server Name Identification
(?)) and Subject Alt Names or Wildcard certificates. SNI extends the SSL
protocol to send the hostname during the client handshake. The Subject Alt
Name extension, which has been more reliable and available for me, adds
multiple hostnames to the certificate for the client to match against.
Wildcards do the same thing, patternistically: *.example.com.

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

~~~
delinka
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.

~~~
oxtopus
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.

------
HNJohnC
I've been spending many weeks reading articles and books about building a
RESTful api. There are a lot of 'ivory tower' guidance articles and books on
REST that make little sense in the trenches.

That article sums up exactly my own distillation into practical terms of all
that information out there. I wish I had read it first.

~~~
icebraining
Look, REST wasn't something invented in Fielding's study, it was a
destillation of an architectural style that was extremely common: Websites.
Many ( and at the time, most) are stateless, follow HATEOAS, using only a
standardized set of methods, etc.

There's nothing difficult or impractical about REST, and the proof is that we
use it every day.

Now, it's not aplicable to every case, of course. In those cases, just use
something else, and don't call it REST.

------
protonfish
I am not sure I follow his point about why HATEOAS is not practical, but I
know that I have been able to make it work in my own REST APIs using content
types. I only return JSON if the Accept header specifies "application/json".
(Which is probably what you should be doing anyhow.) I usually also allow an
HTML fragment response for the "text/html-fragment" Accept type. The default
response type (or if "text/html" is explicitly requested in the Accept header)
is the HTML fragment data wrapped in document markup with any forms necessary
to expose all functionality in the browser (without JavaScript, but just
enough CSS to make it pleasant.) It takes more work, but it not only is the
best documentation, you can point the href property of JavaScript click
handled hyperlinks right to the REST URIs for proper fallback.

~~~
brown9-2
Does your JSON response at the root entry point to the API return something
signifying what all possible operations are?

Does the JSON representation of a Employee object returned URLs as a part of
the body for the resource addresses for any "child" objects?

I don't think it can be considered HATEOAS if the answer to either is no.

~~~
SilasX
>Does your JSON response at the root entry point to the API return something
signifying what all possible operations are?

Why, no, it doesn't, because it takes 3 parameters, each of which can take
10,000 possible values, and I don't want to transmit a trillion options every
time someone pings the root.

I mean, I considered documenting how to pass the parameters on a client's
first entry but the HATEOAS crowd told me I was just re-creating RPC, and I
agreed. So no HATEOAS.

------
kailuowang
RESTful design is still one of the tricky problems I meet on a daily basis.
For example, I have blog application in which each blog entry can have
multiple versions in its revision history. What should the restful api look
like to provide the ability to revert to a certain version?

~~~
beaumartinez
Off the top of my head—have a BlogPost and a BlogPostVersion resource.
BlogPostVersion has all the content, and BlogPost simply has a canonical URL
and a link to a BlogPostVersion.

You could then PATCH the BlogPost with the link to whatever BlogPostVersion
you want to update to.

Curious to see what others would recommend.

~~~
mtrimpe
Indeed. Creating a new version of your post should be a POST to
/posts/X/versions. This would create something like /posts/X/versions/U-U-I-D.

Since REST is all about mapping to the underlying semantics of HTTP you'd then
want to make /posts/X redirect to /posts/X/versions/U-U-I-D

Since there's nothing wrong with updating your resource under the hood (think
of e.g. <http://www.weather.com/weather/right-now/>) posts/X would simply
always redirect to the latest version.

If you don't always use the latest version by definition, then you'd probably
do a PATCH with the new version id to /posts/X, or a PATCH with 'active: true'
to /posts/X/version/O-L-D.

~~~
kailuowang
If I understand your solution correctly, does it mean that it's now the
client's obligation to get the content from the revert-to version and create a
new version and POST it to /posts/X/versions? That should work, but what if I
don't wanna give the client the ability to create version arbitrarily (only
allowed to revert to a pre-existing version)?

~~~
mtrimpe
My first solution was assuming you could not revert. If you want to allow
revert then the client would first call /posts/X/versions, get a list of all
versions and then either do

    
    
        PATCH /posts/X
        { "version": "older-revision" }
    

or

    
    
        PATCH /posts/X/versions/older-revision
        { "active": true }
    

Access control is completely orthogonal to this; so for your sample case you
would just return a 403 for any other calls (like e.g. POSTs to
/posts/X/versions)

------
vyrotek
Great article. I'm actually in the middle of building out a new API. I've
built many RESTful APIs but I'm starting to rethink of a couple of things with
this new one. Does anyone have any good resources on when it's NOT appropriate
to use REST? Or is the assumption that 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. In fact, they are a lot of verbs
which fire off lots of business logic and don't really map well to a single
entity. Some endpoints also need to return very large and deeply filled
entities in a single call.

I've started to investigate JSON-RPC, is that a good option?

~~~
dragonwriter
> 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't really map well to a single entity.

A "verb that firest off lots of business logic" sounds like a RPC-style
metaphor.

In a REST architecture -- and they don't necessarily map perfectly so with
more description I might characterize this differently -- I'd characterize
that as most likely a entity _creation_ (HTTP POST) action (the entity being a
particular _invocation_ of the underlying logic, and containing all the
necessary parameters.)

> Some endpoints also need to return very large and deeply filled entities in
> a single call.

How does this conflict with REST. REST has nothing against "large and deeply
filled entities". (Remember that HTTP is _itself_ a RESTful API, and obviously
is designed for a use case where "large and deeply-filled entities" are
frequently returned.)

You may want to define specific media types for each of these types of
entities to do REST properly, but since in practice you are going to have to
define the structure of the entity returned no matter what application
architectural style you are using, this isn't really a substantial extra
workload for REST.

~~~
steveklabnik
> 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 initiate behavior on the
client, REST is the wrong way to go. See the wealth of WebSockets/Meteor/Real
Time Web (tm) frameworks and their hype for examples of when you'd want to do
this.

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

~~~
steveklabnik
> 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...](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_6)
:

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

~~~
dragonwriter
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.

------
joeblau
Great article. I wish you would have written this a year ago when I needed
this info. I had to learn all of this stuff the hard way. I'm definitely going
to use this as a first resource to give to people that I know who are building
restful APIs.

I'm slightly a bigger proponent of HATEOAS, but if you don't need it yet, I
think you can always add it in later. I've been the giver and receiver of bad
things when it's not followed, but that is generally around massive projects.

------
obelos
I prefer providing a "Range" header for pagination. It's typically used for
retrieving byte-range chunks of large objects, but it's also applicable to
return a subset of a result set, like "Range: records=0-10". This has the
drawback of not being easily applied from within a graphical browser, but I
don't consider that a big priority for a REST API in the first place. Viva la
curl!

~~~
5avage
That's great as long as you're using something with efficient random-access
(SQL). If your datastore/back-end is btree-based, however (say, CouchDB for
example, or Google search results) you're better off with 'next', 'prev',
'first', etc. pagination. Asking for the 50,000th record means skipping the
first 49,999! So, you may be painting your back-end into a corner by counting
on random-access being an efficient operation.

~~~
obelos
The header's ranges-specifier doesn't specify a syntax, so you can use a
docid-based pager just as easily.

------
Kiro
"A RESTful API should be stateless. This means that request authentication
should not depend on cookies or sessions. Instead, each request should come
with some sort authentication credentials."

Doesn't that mean you need to do a database lookup to verify the user with
every request? Seems like a lot of overhead just for the sake of avoiding
sessions.

~~~
jethroalias97
Assuming you are using a distributed architecture, there is no way to verify a
user without at least one database lookup because the request could be coming
into any API server. So in most cases we're not avoiding cookies and sessions
just for the sake of it.

~~~
shaydoc
You don't need to do a database look up if you stuff some context into your
token and encrypt it with a secret key. When the server receives the request
it can simply decrypt the token and deserialize it into some sort of strongly
typed usercontext

~~~
gizzlon
Doesn't this open you up to replay attacks though? Since you can't store that
a token was already used..

~~~
TylerE
Sure you can. Just include a timestamp, and expire the token, at, say, time +
90 seconds, or whatever makes sense for the application.

~~~
gizzlon
I get that you can expire it, and that helps, but it's not the same as use-
once. Of course, just using a timeout is probably fine in many cases,
especially if it's used with SSL. But replay attacks are still possible since
there's a windows where it can be re-used.

~~~
shaydoc
Replay attacks are always gonna be possible unless you use a one time token or
signature, thems the break's..., unless you wish to get into the something you
have and something you know model. How can you do a use once token making
concurrent requests without a strong authentication mechanism client side such
as issuing private keys to clients....and all the PKI admin overhead. I think
its safe to say, that a restful api should be stateless, and bottlenecks such
as session state are not necessary.

~~~
gizzlon
I'll take that as a "yes" ;)

AFAIK, neither signatures or "something you have, know" alone fixes replay
attacks. Since this is a well known problem in cryptography, many solutions
exists. All of which are probably overkill for this use.

~~~
shaydoc
At least with the use of a digital signature and nonce you can guarantee that
the request hasn't been tampered with!

------
samsnelling
Just wanted to say thank you for this. I have been searching for a good
article explaining the details of thinking through building an API. This
really could not have come at a better time for me! Cheers!

------
legedemon
OP has mentioned that 'search' is not a noun and hence can't be modeled as a
resource. First of all, 'search' can be used as a noun in the sense of
quest/query - 'His search for the Holy Grail was fruitful.' Secondly, we
happen to have a multi-model search in our application and we treat it as a
resource. This has worked out very well for us and our users can easily craft
search queries just like for the rest of the RESTful resources.

------
centro
REST isn't enough.

To do it right use the HATEOAS constraint.
<http://en.wikipedia.org/wiki/HATEOAS>

And use application/hal+json <http://stateless.co/hal_specification.html>

The more we follow these simple constraints the more we can start to build
tooling to consume any API without having to know much about it ahead of time.

That said, well written article.

~~~
dragonwriter
> REST isn't enough.

> To do it right use the HATEOAS constraint.

The HATEOAS constraint is part of REST; if you aren't using it, you aren't
doing REST.

------
CodeFoo
Great article, I've read many like it, BUT what I can't find is information
pertinent to how one should host their API. I submitted an "Ask HN"
(<https://news.ycombinator.com/item?id=5820761>) earlier, but could some folks
please advise me on the hosting side of "Designing a Pragmatic RESTful API"?

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

------
maxisnow
Before leaving my current place, our Architect built a PHP micro-framework for
our APIs that follows 90% of what's outlined here. I never really understood
the magnitude of his work until I tried developing a new API in a different
framework. Intelligent routing and query param handling all baked in is so
rad.

------
l1ghtm4n
Excellent article. I've just written up REST API design patterns for our group
here and it maps very closely to the guidelines you've outlined. Many other
posts about REST design are lacking real world experience items like rate
limiting.

------
pragueexpat
What about jsonrpc (<http://json-rpc.org/>)? I am using it in a project and I
really appreciate the simplicity. Would be curious to hear from others who
have experimented with it.

------
walshemj
Well just as long as you use the right paradime REST is not always the best
model to use.

I built a tool to use a third partys restful api for a when they should have
built it using message queuing as that suited the application.

------
MostAwesomeDude
Don't limit yourself to JSON. Your dislike of XML does not mean that JSON is
always the right answer. Instead, write code that flexibly can render to any
of a set of formats, and use content negotiation to determine which format the
user agent wishes to consume. This lets you do things like let the read-only
portion of your API be accessible via browser, and it will future-proof you.

~~~
jfaucett
when he says "use JSON where possible XML only where you have to", I thought
it was funny, like developers out there are just dying to use this verbose
behemoth instead of its terser cousin json. But anyways, I agree with
everything you're saying just wondering if there actually are any devs out
there who just adore some sweet XML (seriously) ?

~~~
veesahni
OP here. I got an email with an interesting argument on the topic.
Paraphrasing: Today JSON is hip, tomorrow may be something else. By supporting
XML by default and using XSLT to translate it to alternate outputs, you're
able to support multiple formats without having to modify your software
itself. Ofcourse, this does come with the cost of having to maintain XSLT
files.

To businesses that need to support multiple formats (enterprise
requirements?), XML + XSLT sounds like a fair approach - it allows you to
simultaneously create idiomatic XML & JSON

~~~
dragonwriter
> By supporting XML by default and using XSLT to translate it to alternate
> outputs, you're able to support multiple formats without having to modify
> your software itself.

By separating out the rendering-to-an-output format from the basic logic of
the application, you get similar benefits without creating a dependency on XML
handling libraries and requiring another implementation language (XSLT) for
the rendering component.

