
The Good, the Bad, and the Ugly of REST APIs - apievangelist
http://broadcast.oreilly.com/2011/06/the-good-the-bad-the-ugly-of-rest-apis.html?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+oreilly%2Fnews+%28O%27Reilly+News+and+Commentary%29
======
vyrotek
_Map your API model to the way your data is consumed, not your data/object
model_

I'm glad this was brought up. I feel I'm constantly battling with myself on
this issue. The purist in me always wants to create REST endpoints that return
just the minimum info you'd expect from that URL which represent my model
perfectly. The result is requiring customers to call the service a lot. But
sometimes if you take a step back and think about how it will be consumed you
can really do your consumers/customers a favor. Although, if not carefully
thought through you could end up doing more 'work' and returning data that is
always discarded from the response.

~~~
joelhaasnoot
This thinking can however also be taken to far. The Dutch Railways recently
released an API for all their trip planning, live departures and pricing info.
Unfortunately, it's mainly a way to get at the API their apps call: it's all
presentation based.

For instance, up until recently there was no way to tie a certain train
service listed in a given trip to the same service in the live departure
endpoint. It's also still not possible to tie a train service to its schedule.

They've taken their API and made it all consumer-oriented and it's gone
overboard.

------
stevenp
"I know you love {JSON,XML} and you think everyone should be using {JSON,XML}
and that the people who use {XML,JSON} are simply stupid."

Does anyone love XML and hate JSON?

~~~
epynonymous
right, i can't think of anyone that prefers xml over json-- xml seems too
bloated, dom and sax parsers require lots of code to walk trees compared to
just a single json parse call and then you can just directly access things in
an object. though i have had to write several json decoder/encoders for
special objects.

for my internal rest apis, the only response format i provide is json, this is
for mvp purposes. though i will add xml when i publicize these apis.

~~~
artsrc
My understanding is that REST imposes a bunch of restrictions about how an API
is suppose to work.

For example the idea that you can just communicate a single base URL and
document formats, and other urls are deduced from that. Which add complexity,
but make the system more able to evolve.

My thinking is that these constraints are inappropriate for an internal API,
where you could embed knowledge of how to construct a number of URL's in
clients.

Also some tools, like .NET, have good support for mapping XML schema's to
classes, and I don't know of equivalents for JSON.

------
extension
_REST is good, SOAP is bad_

The irony is that SOAP is a lot closer to being RESTful than RPC-over-HTTP aka
"REST API", because SOAP actually attempts to have a uniform interface driven
by hypertext (WSDL). That doesn't mean it's easier, but REST is not supposed
to be easy.

------
epynonymous
"Meaningful error messages help a lot"

the beauty of rest is that you piggy back off the error codes of the http
protocol, e.g. 403 forbidden, 404 page not found, 500 internal server error.
of course you could always add text in the response providing more detail, but
i argue that this is not very helpful in all cases, what can you as the api
consumer do if the server is barfing back something cryptic (503)? the use
case i can think of is for an errant parameter in the request, i'm a firm
believer of the client app doing field validation, of course that doesn't
absolve the server from having to also do it. but instead of providing a 500
(internal server error), i think there could be something more meaningful like
a 400 (bad request) followed by some response parameter with more detailed
information like "your address field contains a float".

the example given for authentication is a poor choice, there are security
reasons why you would want to be vague, returning the fact that the password
is mistyped only tells the consumer of the api that this user exists, please
hack me.

the one thing i hate about rest is how to document the endpoints and the
various http statuses that could be returned, if someone could generate a
script that could help me here (for python) that would be appreciated.

~~~
epochwolf
Rails uses 422 for invalid input.

Which wikidepia says[1]: Unprocessable Entity (WebDAV) (RFC 4918) The request
was well-formed but was unable to be followed due to semantic errors

1: <http://en.wikipedia.org/wiki/List_of_HTTP_status_codes>

------
jimbobimbo
"And while you're at it, don't use HTTP authentication either. Use signed
queries that authentication each API call individually."

What is the problem with using digest auth with proper request counter (nc)
incrementing done over HTTPS?

~~~
boucher
What's the problem with HTTP Basic auth over HTTPS?

~~~
bbsabelli
Cost?

------
credo
>> _And while you're at it, don't use HTTP authentication either. Use signed
queries that authentication each API call individually._

Beyond server-server api calls and authentication, I'm curious to know what
folks think about authentication and individual-user client apps making api
calls to a server.

If you build a web service whose REST apis are only intended to be consumed by
customers of your $0.99 mobile app, one option is to use no authentication at
all. This means that a third-party may potentially write another $0.99 app
that "steals" your web-server resources.

Has this been a problem and what (if any) schemes (e.g. digest auth, facebook
login etc.) have you used to mitigate the problem. (facebook login etc.
doesn't fully address the problem unless you can distinguish between facebook
users who have purchased the app and facebook users who haven't purchased the
app )

~~~
jimbobimbo
Why not to use client cert and HTTPS or HTTP digest authentication with same
password across clients? In order for third-party to create their client, they
have to go through reversing procedure, which would be unlawful.

~~~
derefr
You expect that the third-party co-opting your server resources would be in US
legal jurisdiction?

~~~
jimbobimbo
I expect this will give me firmer grounds whenever I need to send DMCA
takedowns.

------
j_baker
_Failing to realize that a 4xx error means I messed up and a 5xx means you
messed up_

More often than not, this seems to boil down to bad error handling than it
does lack of understanding.

------
jschrf
I love the simplicity provided by a good REST API.

ESRI's REST platform is a good example of a nice, clean API. Very easy to
diagnose and resolve issues, especially with tools like Fiddler.

A really nice feature to have in a REST API is the ability to run operations
in an HTML form. With this, you can re-run requests in the browser and tweak
parameters to help you diagnose issues. Very useful.

~~~
tlrobinson
I prefer Charles: <http://www.charlesproxy.com/>

~~~
jschrf
Looks good. I'll give it a try, thanks.

One problem I have is dealing with viewing my Comet connection (long-lived
XHR). I stream JSON to the browser and Fiddler picks up and is able to display
all this data, but prevents it from being received by the browser. Would be
nice to not have this problem so I can see my JSON events in Fiddler and in my
UI.

~~~
terinjokes
Can you let us know if you had better luck with Charles?

~~~
jschrf
Sure thing.

------
regularfry
Speaking as someone who's currently building a cloud API, this makes a _lot_
of sense.

------
neeleshs
To me, throttling and chatty APIs seem to be orthogonal. These apply to REST
or SOAP or any other API.

EDIT: I'm wrong, chatty is specific to REST.

