Get Your API Right

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.

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.

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