Recently we have been working on developing an API for our Social Brain Framework and as it is completely new for me, it has been quite a challenge.

The idea of writing this article started from this post on NICAR-L list for investigative journalism. The guys at Protopedia, the awesome Chilian project for mapping political relations on American continent are starting to build their API. They were looking for some of the best practices, so people sent a few links out on the list. After some investigation of myself, I have decide to make a write-up with all discoveries about API best practices and development workflow.

DISCLAIMER :
This article is mostly a straight rewriting of sources quoted at the bottom. I didn’t add much of my own, just copy/paste and organized the content to make this write-up.

I always hear about “REST”, but what does it means exactly?

REST is an acronym for Representational State Transfer, but this doesn’t help at all. Actually, a loosy definition from Ben Ramsey is “any simple interface that transmits data over HTTP without an additional layer”. 

Know let’s look at some characteristics of RESTful API. They are :

  • Focus on accessing a diversity of resources (nouns), NOT actions  (verbs)
  • Every resource is uniquely addressable
  • All resources share the same constrained interface for transfer of state (actions) and content types
  • Must be stateless, cacheable, and layered

One great propery of RESTful API is they should have clean well-designed URLs, which means

  • clear hierarchy
  • hackable, can be reverse-engineered
  • clear meaning and are not obfuscated
  • can be very long or very short

They are based on CRUD (Read Update Create Delete) which is based on HTTP methods :

  • GET : Transfers (“copies”) a representation from resource (server) to client
  • PUT : Exact opposite of get – from client to resource
  • POST : Has the same meaning as “paste after;” that is: “add to what you have; don’t overwrite it”
  • DELETE : requests that the resource identified is destroyed or removed from public web


Now how to design a RESTful API? What’s the workflow?

Some good advices about how to start writing an API from Joshua Bloch of Google in its slides about API design :
  • Your job is to extract true requirements :  you need first to define real use-cases
  • Start with Short Spec : 1 Page is Ideal
  • Bounce spec off as many people as possible and listen carefully to their feedbacks
  • Start to code it out as you gain confidence with your draft
  • Write code often, even with unfinished spec. Code lives on as examples, unit tests.

This sounds pretty much like any best practices for development, but always good to hear it anyway.

Now let’s focus on a specific workflow for your API implementation.

  1. Determine your resources clearly (i.e all things you will need to access inside your app)
    <code>/users <br clear="none" />/users/username <br clear="none" />/users/username/favorites<br clear="none" />/users/username/tags
  2. Decide what methods each resource will support
    /users GET POST PUT<br clear="none" />/users/username GET POST PUT DELETE<br clear="none" />/users/username/favorites GET PUT<br clear="none" />/users/username/tags GET PUT
  3. Observe how resources links together
     tags --> users
  4. Develop your data schemas
    /users<br clear="none" />id<br clear="none" />username<br clear="none" />firstname<br clear="none" />lastname
  5. Rationalize and refactor your schemas
    try to remove  duplicates, clean relationships, etc.
  6. Choose the best content type/format to represent your schemas
    Most popular content type are XML, JSON and plain text, but you should need MIME or other for images


To finish, there is a list of API Best Practices (c) 

1. API must be clear
  • Easy to learn
  • Easy to use, even without documentation
  • Hard to misuse
  • Functionality should be easy to explain
  • Names should be largely self-explanatory
  • Names should be consistent: the same word should mean the same thing through the whole API
  • API should be regular, have some symmetry

2. API should be well-documented
A good API Documentation should contains
  • a full example
  • expected response of the example (in all formats)
  • listing of error codes and what they mean
  • versioning  - and deprecation schedules

The documentation should be searchable HTML interface (no pdf)

Some tips to document every class, interface, method :
  • Class: what an instance represents
  • Method: contract between method and its client
  • Preconditions, postconditions, side-effects
  • Parameter: indicate units, form, ownership
3.  An API RESTful or at least RESTlike
  • No need to become a RESTafarian (a sort of REST extremist), but let's try to keep close to a RESTful design
  • Having sensible resource names/paths (e.g., /posts/23 instead of /api?type=posts&id=23)
  • Use both XML and JSON for a web API output (best is to be able to chose with extension .json or .xml)
  • Focus on clarity. Your API implementation does not have to mimic your underlying application architecture.
4. API should be appropriate to audience 
Look at your API from the standpoint of a consumer.
Maybe try building something small using your own API – it can be an eye opening experience.

Principle of Least Astonishment : User of API should not be surprised by behavior
_ It's worth extra implementation effort
_ It's even worth reduced performance

5. API should be secure
Good authentication system, easy for the user but also safe for the app
  • OAuth/OAuth2
  • user/password
Minimize Accessibility of Everything
_Make classes and members as private as possible
6. API should be sufficiently powerful to satisfy requirements

Here are the sources of this article, which is largely plagiary

API examples
Klout’s Docs use Mashery’s I/O Docs, which is based on Wordnik’s API docs http://developer.klout.com/iodocs