The Web API Checklist

checklist.md

REST API Checklist

Tried to keep list concise as possible. Following points are actual specs, de facto conventions or good pratices.

• Use nouns, avoid verbs (/getAccount/123 => /accounts/123)
• Plural form
• Base url: https://api.example.com (prefered over https://example.com/api/)
• Versioning: https://api.example.com/v2/ (alternative: Accepts: application/json;application&v=2)
• camelCase (most APIs are JSON based, JSON is JavaScript, Underscores are not JS convention)
• Timestamps (2004-02-12T15:19:21+00:00 - ISO8061)
• Pagination (GET /accounts?offset=0&limit=25)
• Descriptive errors (see below)
• Partial representations (GET /accounts/123?fields=username,name,surname)
• Idempotent methods (http://restcookbook.com/HTTP%20Methods/idempotency/)
• Content negotiations (http://programmers.stackexchange.com/questions/139654)
• CRUD (http://stackoverflow.com/questions/6203231)
• Use specific status codes (respond with 201 when creating resource instead of 200; in short, complete)
• Do NOT create your own schema (Use existing protocol: OAuth 1.0a, OAuth2, Basic only over SSL)
• Use API Keys instead of username/password pair (where feasible)
• HTTP Compression

Bonuses

• HTTP Method overwrite (POST /accounts/123?_method=DELETE)
• Caching (http://fideloper.com/api-etag-conditional-get)
• Conditional Modifications (same idea as above, but to "to prevent inadvertent modification of the wrong version of a resource")

Descriptive error example

Seeing following error response saves time for developer who reads them. Think what you YOU like to see as response.

• code - if there are several reasons to give 409, you need way to distinguish them easily
• property - field at fault
• message - message for user
• moreInfo - the RTFM link for developer

409 Conflict
{
    "status": 409,
    "code": 40924,
    "property": "name",
    "message": "A Directory named 'Avengers' alredy exists.",
    "developerMessage": "A directory named 'Avengers' already exists. If you have a stale local cache, please expire it now.",
    "moreInfo": "https://www.example.com/docs/api/errors/40924"
}

Sources

1. https://mathieu.fenniak.net/the-api-checklist/
2. http://tools.ietf.org/html/rfc2616 - HTTP/1.1
3. http://www.ietf.org/rfc/rfc3339.txt - ISO8601 (Time format)
4. https://www.youtube.com/watch?v=hdSrT4yjS1g - "REST+JSON API Design - Best Practices for Developers"
5. http://en.wikipedia.org/wiki/List_of_HTTP_status_codes