Wego Engineering

API guidelines

Wat

A guide for the times when you're creating an API, either public or internal.

General principles

• REST is good but don't follow it 100% into an ivory tower.
  • Use the HTTP verbs and HTTP status code conventions.
  • But not to the extent of being impractical. Read this SO response to versioning REST APIs - I disagree with this approach because it's still impractical at this point in time (at least until HATEOAS really takes off).
• Use plurals for resource URLs. E.g. use /searches instead of /search, /hotels/123 instead of /hotel/123.
• Always include API version in URLs, e.g. /v1/searches. Make the version mandatory.

API response guidelines

• Support JSON as the default response format, i.e. if no Accept header is send, respond with JSON.
• Send the correct Content-Type response header:
  • JSON: application/json
  • JSONP: application/javascript
• For JSONP requests, always return HTTP 200 so that browsers can handle 4xx and 5xx errors, with separate meta and data fields, e.g. { meta: { status: 400 }, data: {} }. Note that the actual HTTP status is included in the response as response['meta']['status'].
• Support CORS (Cross-Origin Resource Sharing).
• Use ISO 8601 format for all times and dates.
• Partial responses are a good way to reduce API responses to only what's needed. Use the fields parameter as a convention.
  • E.g. /v1/hotels/123?fields=name,stars,location.code
• Pagination: it's a good idea to include metadata about total number of records.
• Rate limits: return these as X-RateLimit-Limit and X-RateLimit-Remaining headers.

API request guidelines

• Use api_key as parameter name for API key.
• For POST requests, other than supporting params in the request body in the standard way (e.g. foo=bar&page=1), you can also support JSON-encoded params in the body. The request Content-Type should be application/x-www-form-urlencoded.
  • E.g. curl -i -u username -d '{"scopes":["public_repo"]}' https://api.github.com/authorizations
• Pagination: use page and per_page params as a convention.
• Language/locale: use Accept-Language header (preferred) or locale param.

Error responses

• Send the appropriate HTTP status code and explain what each code means in API documentation.
• Remember that error responses are for API developers - make debugging errors easy for them by providing as much information as possible.

• A good convention to follow is this:

  {
    "status": 401, // HTTP status code
    "error_type": "invalid_auth", // Additional error type - explain this in docs
    "developer_message": "Invalid API key." // Word this message for API developers
    "user_message": "This application has not been authorized." // A message for actual users to see. Optional.
    "more_info": "http://developer.wego.com/v1/hotels" // URL to helpful API documentation.
  }