Public API Checklist

Below is a checklist that developers should go through before making APIs public.

  1. APIs must return JSON. Exceptions to this rule are APIs where the user is specifically requesting for non JSON data. For example, requesting a CSV file or a debug file.
  2. The API should be available if requested with a bearer token from the integration platform.
  3. There are scopes that can be selected in the integration platform that enables or disables access to the resource exposed by the API.
  4. If the API call being made is resource intensive on Sentry's infrastructure, there is a rate limit in place which rate limits excessive calls.
  5. APIs returning a variable number of elements as a list should be paginated. They should be paginated using the link header standard.
  6. End user requests should not easily be able to trigger 5xx errors in our application by manipulating request data or sending invalid/malformed data.
  7. There are tests associated with the API which look for correctness. There should also be tests that check the response format to ensure the API does not deviate from its contract.
  8. The API should return the same format for a status code, irrespective of the input provided. The content can be different but the response format should be the same.
  9. When an API is only available when certain feature flags are enabled (perhaps through a pricing plan), the API should check for that. If a bearer token of an organization who does not have access to the feature is used, the API should return with a 403 Forbidden and an error explaining which feature flag is required.
  10. APIs should use camelCase for query parameters and request/response bodies.
You can edit this page on GitHub.