On RESTful API Standards – Just Be Cool: 11 Rules for Practical API Development

http://techblog.appnexus.com/2012/on-restful-api-standards-just-be-cool-11-rules-for-practical-api-development-part-1-of-2/#more-1299

by jedwards_tech • 14 years ago

72 34 14 years ago

techblog.appnexus.com

DropkickM162• 14 years ago

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

thelarry3• 14 years ago

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

DropkickM162• 14 years ago

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.

rfugger• 14 years ago

I doubt Fielding would agree:

"The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations."

http://weblogs.java.net/blog/mkarg/archive/2010/02/14/what-h...

digitallimit2• 14 years ago

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.

richardlblair3• 14 years ago

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.

thelarry3• 14 years ago

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.

pfraze4• 14 years ago

Is it feasible to create subresources for each partial put? For instance, if the `/person/:id` resource has an address as part of the data, could you do PUT `/person/:id/address` to only overwrite the address?

ExpiredLink• 14 years ago

I found this to be practically useful:

http://www.youtube.com/watch?v=QpAhXa12xvU&list=PLD90BAD...

alexchamberlain3• 14 years ago

ARGH! PATCH is for partial updates, not PUT!

ajross3• 14 years ago

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.

tvon3• 14 years ago

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.

alexchamberlain3• 14 years ago

As someone else said, the API is the UI for the developer. It should be as intuitive and straight forward as possible. I would expect PUT to replace a resource at a specific URL and POST to create a resource under a URL. Therefore, to do a partial update, we need a new verb.

Having said that, I like subresource URLs and using PUT to do partial updates like that.

voyou• 14 years ago

Why? What's the actual problem with using PUT for idempotent partial updates?

pfraze4• 14 years ago

Consistency. You're entitled to break verb conventions, but you may confuse newcomers or force API consumers to special-case for you.

poutine• 14 years ago

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.

richardlblair3• 14 years ago

Yes! Thank you.

fink01362• 14 years ago

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• 14 years ago

All generalizations are bad.

digitallimit2• 14 years ago

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.

fink01362• 14 years ago

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.

On RESTful API Standards – Just Be Cool: 11 Rules for Practical API Development

Related Stories