

Get Your API Right - mapleoin
http://wonderfullyflawed.com/2009/07/02/get-your-api-right.html

======
DougWebb
I like everything the author mentions, with one addition: besides XML and JSON
as media types, I like to provide xhtml with a microformat. This allows
browsers to interact with most API functionality directly, which has
development benefits you just won't realize until you try it.

The key is that your xhtml must be generated dynamically from an internal data
structure, and your JSON and XML should be generated dynamically from the same
data structure. This ensures consistency both within and across media types,
and it simplifies development because you can stop worrying about the output
format; you just need to worry about the internal data structure which
represents your resources. The transformation into a client-usable
representation occurs completely separately from all of your business logic.

------
wccrawford
The author says never to put data in attributes, always put it in tags. He
shows and ID tag inside and ASSET tag.

The ID should be an attribute, and all the other data should stay as tags.
This is because the ID won't change and identifies the ASSET. Anything else
could change and is just data.

------
mikek85
these are important

1\. use hyperlinks and link relations i.e. <link href="/people/bob"
rel="friend" />

2\. don't bother with multiple media types (unless /absolutely/ necessary) .
If appropriate try to use/extend an established type such as Atom/AtomPub

3\. make sure you set your cache control headers appropriately

