Comments on: Get Your API Right

By: Notional Slurry » links for 2010-03-10

Notional Slurry » links for 2010-03-10 — Thu, 11 Mar 2010 06:04:04 +0000

[...] Get Your API Right « Trek "Every project I’ve worked on in the last two years has heavily involved the use of web APIs. Libersy at the time (no idea about now) had an architecture that was extensively API based, even for communication between internal applications (an architecture I strongly argued against, bee tea dubs). Since then I’ve futzed with web APIs almost exclusively. From very narrow focused uses like University of Michigan’s Bluestream Service, to more broad but still fairly local APIs like the Ann Arbor District Library’s soon-to-be-updated API, all the way to APIs of major web applications like Twitter and Flickr. [...]

By: wonderfullyflawed

wonderfullyflawed — Thu, 07 Jan 2010 21:50:29 +0000

According to the spec: “The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line”

In examples urls above (e.g. “/photos” and “/photos/somephotoid”) “/photos” is the existing resource (the collection of all photos) a POST request asks to create a new subordinate (in this case, a new photo).

PUT handles entirely new entities or, if the Request-URI represents an existing resource “the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server”.

In this case PUT to the collection would, I’m assuming, mean either create “/photos” as an acceptable new resource if it did not exist, or alter the resource represented at “/photos” in some way.

By: ZeissS

ZeissS — Thu, 07 Jan 2010 17:30:42 +0000

Are you sure you got POST and PUT right? Afaik PUT is for creating resources, not POST.

By: Code Mongrel | Episode 2: A Festivus for the REST of us!

Code Mongrel | Episode 2: A Festivus for the REST of us! — Mon, 27 Jul 2009 10:04:02 +0000

[...] Get your API right [...]

By: Simone Carletti

Simone Carletti — Sat, 18 Jul 2009 12:51:37 +0000

Great article!
I have been planning a post like this since I wrote about Technorati API a couple of years ago http://www.simonecarletti.com/blog/2007/11/technorati-api/

I would integrate your list with the following points

1. Return request arguments in response

Including query parameters so that I can easily fetch them without the need to store/validate them everywhere. Returning request parameters also enable the developer to verify wether the API interface correctly understood my request (ex I passed foo=bar and it didn’t understand foo=1 due to a cast to int).

2. Provide consistent response.

If you have multiple API methods do not change root node or change it accordingly to the request.
Also, if you use an error node to return errors, always use it.

For instance, http://technorati.com/developers/api/bloginfo.html returns an empty response with URL when the URL is not a blog, http://technorati.com/developers/api/blogposttags.html returns an error.

3. Return meaningful error messages

It’s always a good idea to return an error status along with a full explanation.

4. Provide a comprehensive documentation

Also make sure your documentation is up-to-date and reflects the real API interface.

5. Do not drop old API URIs/methods, use a coherent error message or status code (410)

6. Include schema/api version in the response

In this way developer can create intelligent libraries that validates and supports multiple API versions.

7. Don’t change node order or container

For instance, Technorati sometimes puts inboundblogs/inboundlinks within weblog tag (TestGetInfoSuccess.xml) and sometimes outside (BlogInfo, Cosmos).

By: Robert J Stinklestein

Robert J Stinklestein — Thu, 16 Jul 2009 15:27:42 +0000

Sir,

I have attempted to access your periodical at great expense over the telegraphy wire STOP.

Please endeavor to use fewer characters in the future STOP

By: wonderfullyflawed

wonderfullyflawed — Thu, 16 Jul 2009 15:10:26 +0000

@commenter
Oh, that’s very true!.

However, this thread isn’t an indication of it.

I write about IA, standards based web stuff, and development in a *NIX environment. My Win/IE readership (especially IE6 where the contrast is a particular issue) is 2.2%. I have more readers who speak English as a foreign language that people who use IE. And, yet, none of them come in saying “What is the point of publishing an unreadable opinion piece? Roman characters, English grammar. Why make it difficult? Ever heard of Chinese?

By: commenter

commenter — Thu, 16 Jul 2009 10:03:48 +0000

“I suspect it’s only an issue on IE/Windows. In that case, you’re specifically not my target audience.”

Arrogant dick.

By: John O'Shea

John O'Shea — Thu, 09 Jul 2009 21:04:32 +0000

@Joel Potishchman we were playing with your approach but we’ve discovered that while our “cripplied” client (a flash player based ria) is capable of setting a custom HTTP Request header, flash does not appear to provide an API for getting HTTP response headers (specifically one like the X-True-Status-Code header in your example).

Are we missing something?

By: wonderfullyflawed

wonderfullyflawed — Thu, 09 Jul 2009 15:53:00 +0000

@Joel Potishchman: true, that’s a fine use of POST as long as you follow the spec and send back “either 200 (OK) or 204 (No Content) … depending on whether or not the response includes an entity that describes the result.”