API conventions

To reduce the amount of redundant documentation and maintain a level of consistency throughout the web APIs, there are certain conventions that will be adhered to:

Terminology

The following terms will be referenced throughout documentation:

  • Client: An external application that interfaces with backpack.tf through the web APIs.
  • Resource: A repository of entities exposed through the web API in a RESTful manner.

HTTP verbs

Resource APIs in particular will make good use of HTTP verbs, or request methods. The standard GET will be used for all non-destructive APIs that only return data, whereas any idempotent operations will use POST, PUT, PATCH and DELETE for creation, replacement, modification and deletion of a resource. POST requests will also be used in non-resource-based APIs that perform actions.

Response types

The Accept request header is not mandatory. Response type defaults to JSON for APIs that support multiple formats.

Status codes

We try to make sure that the HTTP status codes are self-describing and helpful. The following status codes will be produced by the web APIs under certain circumstances:

  • 200 OK: A standard error-free response type for most methods.
  • 201 Accepted: Used in place of 200 OK if the request resulted in the creation of a resource, such as in POST methods.
  • 204 No Content: Used in place of 200 OK if the response is never expected to return a body, such as in DELETE methods.
  • 400 Bad Request: Indicates an error with the supplied request body.
  • 401 Unauthorized: Indicates an error with user authorization. This will only be returned if the API key or OAuth user session is invalid.
  • 403 Forbidden: Implies an error with user access control for a resource. The user may not own the resource, or could perhaps be banned from interacting with the resource.
  • 404 Not Found: Returned if a resource cannot be found.
  • 422 Unprocessable Entity: Indicates a validation error on the request body.
  • 429 Too Many Requests: Returned if the client is being throttled.
  • 500 Internal Server Error: Indicates a fatal error on the server.
  • 501 Not Implemented: On resource APIs, will be returned if a request attempt is made to a resource that does not support that request method.

Certain error responses may return a body with more information about the error. This is usually a JSON document with at least a message field.