
On RESTful API Standards – Just Be Cool: 11 Rules for Practical API Development - jedwards_tech
http://techblog.appnexus.com/2012/on-restful-api-standards-just-be-cool-11-rules-for-practical-api-development-part-1-of-2/#more-1299
======
DropkickM16
I don't think adding metadata to your responses goes against the ideas of
HATEOAS. On the contrary, HATEOAS requires enough metadata about the
application state and possible transitions so that a consumer can fully
interact with the API without relying on out-of-band information (URL patterns
being the most common example).

~~~
thelarry
Some people argue that whatever you get back from the request should be the
exact json/xml/whatever object representation.

~~~
DropkickM16
Can you point me to a source for this argument? I'd be interested in taking a
look at the reasoning behind it. Obviously, that's an approach that a lot of
people take for pragmatic reasons, but it doesn't seem to allow the kind of
hyperlinking that's the core idea of HATEOAS. Of course, the term "object
representation" is pretty generic, and may obviously somehow include links to
related resources and application states.

------
poutine
Yes, pretty much this is how I've been doing JSON API's for a couple years
now. Making things all about convenience and ease of use for the API consumer,
that's really what an API should be about. Afterall, API's are UI for
developers.

~~~
fink0136
Generalizations are bad. At work, although our front end uses our REST API, it
is also used by many different backends of clients that integrate with our
service.

~~~
pstuart
All generalizations are bad.

------
fink0136
Developers that view "Practical API Development" as something more important
than agreed-upon standards is also the reason Microsoft Internet Explorer has
a long history of suck.

"But honestly, why would your users be creating an object with an id?" They
aren't. You should not be PUTting endpoints with an id. I get more more and
more scared as I type, thinking about this change-the-standard-for-my-own-
purpose attitude.

------
digitallimit
I'd appreciate other people's input on these choices. I'm currently
implementing an API much in the way of these standards, but I'm almost
buckling and implementing PATCH since I feel dirty having PUT do so much, so
incorrectly.

~~~
richardlblair
You have to analyze your target audience. Will people who are new to using a
restful api being using your api? Will you provide a wrapper yourself?

There are about a million questions you must ask yourself in order to come to
the right answer for YOU. At the end of the day what matters is that the
person using your API finds it easy and intuitive. If that means that you use
PUT for updates, and POST for creation, so be it. It could even mean that you
convert PUT to POST requests, and treat them all the same. If you take that
route, you check to see if the resource ID is specified in the post data. If
the ID is in there, you update that resource, if it's not in there you create
a new resource.

While you go forward, keep in mind one thing. If your API is hard to use then
no one will use it. If no one uses it, then your API doesn't matter. If your
API doesn't matter, then you made all the wrong decisions.

Also, have fun with it. Creating APIs is incredibly fun, enjoy yourself, and
enjoy creating something people will enjoy using.

~~~
thelarry
One thing to keep in mind about wrappers is that now a days kids like
accessing APIs from mobile applications. With iOS you cannot simply just wrap
curl calls like you would in PHP. Developers use weird and random REST API
accessing frameworks in iOS.

~~~
richardlblair
I would be interested in finding out more about these REST API accessing
frameworks in iOS. Do you have any links?

~~~
thelarry
Just off the top of my head I know of
<https://github.com/AFNetworking/AFNetworking>,
<http://allseeing-i.com/ASIHTTPRequest/> (no longer supported but still used),
and <http://restkit.org/>

------
alexchamberlain
ARGH! PATCH is for partial updates, not PUT!

~~~
ajross
Does this really rise to the level of an "ARGH!"? I mean, look: REST is nice
because it simplifies front end network APIs that were getting out of hand.
That is its value.

Replacing the nonsense of SOAP and XML-RPC with equally ridiculous pedantry
about HTTP minutiae is not helping your cause nor your software.

~~~
tvon
There are all of _nine_ HTTP methods, using them correctly should not be that
difficult.

edit: Well, ajross has a point. There are actually all of _eight_ HTTP 1.1
methods, and PATCH is not one of them.

~~~
ajross
The cargo-cult fallacy that there is a "correct" way to do something as
complicated and varied as web service provision is exactly the kind of
nonsense I'm talking about.

It is "easy" to blindly follow any rule. In most cases it is also wrong.

~~~
superasn
Also how do you make a PUT or PATCH request from programming languages like
Actionscript (and quite possibly Javascript though I'm not sure) which only
support POST and GET requests currently?

~~~
grabastic
Many frameworks overload the POST operation and allow the desired verb to be
specified in the data.

Rack::MethodOverride does this for Rack-based apps by using the value of the
_method parameter as the http verb.

------
ExpiredLink
I found this to be practically useful:

[http://www.youtube.com/watch?v=QpAhXa12xvU&list=PLD90BAD...](http://www.youtube.com/watch?v=QpAhXa12xvU&list=PLD90BADB5FD29BB3E&index=7)

------
digitallimit
In a lot of APIs I've dealt with, you can create resources with ids that match
your own resources, hence wanting to use PUT for creation, e.g. if you have
users in your application and you want to extend them to this web service,
instead of having to store an additional "foreign key" per user, you can just
PUT users in the web service with ids from your own service.

I'm doing this for the API I'm building, as modeled on FatSecret's API.

