Sign In

Making an API Public

Introduction

In this document, we explain both how you make an API public and the considerations to take into account before doing so.

Definitions

Managed Client

A managed client is one that Sentry controls, such as our frontend. In this type of client, we control both which endpoints are used and the attributes used by those endpoints.

Partially Managed Client

A partially-managed client is one that we only partially control, since we do not control the version of the client that is running for our users; for example, our Sentry CLI. While we control the endpoints the CLI uses, once the CLI is installed and running in a customer's implementation, we don't control the version of the client a user runs.

External Client

An external client is a client that Sentry does not control; for example, a script written by a customer run in their repository, or an integration written using the Integration Platform. For this type of client, we have no control over the endpoints they choose to use, nor can we require that they immediately update their endpoint.

Private API

A private API is an undocumented API. Sentry can make breaking changes to this type of API, and no one will blink an eye.

Public API

Our public API is documented at https://docs.sentry.io/api/.

Private Attributes in a Public Endpoint

You can have private attributes within a public endpoint.

As an example: https://docs.sentry.io/api/teams/retrieve-a-team/. The response has multiple attributes:

Copied
{
  "id": "2",
  "slug": "the-interstellar-jurisdiction"
  ...
}

Let's say we also return a nickname for a team. If what is returned is not documented as a response in our public documentation, that attribute is a private attribute within a public endpoint.

API Versioning

Currently, Sentry's API is v0 and is considered to be in draft phase. While we don't expect our public endpoints to change greatly, keep in mind that our API is still under development.

Making an endpoint public

When you make an endpoint public, you're committing to always returning at least the set of defined attributes when that endpoint is called. As a result, the attribute(s) cannot be removed from an endpoint after they are public. Additionally, the type of the attribute cannot be changed once the attribute is public. The reason the attribute and its type cannot be changed is because both external and managed clients are relying on the public attribute to be returned from that endpoint.

You can add attributes to a public endpoint.

When to make an API public?

Making an API public offers considerable benefits. A public API allows our customers to incorporate Sentry into their workflows. It also gives Sentry more visibility in our customers' organizations ("Woah that's cool data, where'd it come from?"..."Sentry!"). Remember, however, making an API public means that once an endpoint is public, you can only add to it: You cannot make any breaking changes.

As a guide, use these questions:

  1. Is the feature for which you're making the endpoint stable?
  2. Will the API change substantially in the future?
  3. Does the API offer value to customers who are accessing it?

If your answers are Yes, No and Yes, you're in business - make the API public.

How to make an endpoint public?

We use Open API Spec 3 to write our API documentation. You can find that content here: https://github.com/getsentry/sentry/tree/master/api-docs. You can find the tests here: https://github.com/getsentry/sentry/tree/master/tests/apidocs.

Local development

To add documentation for a new endpoint:

  1. Create a new file for your schema under the appropriate folder here. Document the schema for the relevant requests.
  2. Add the new path to this file.
  3. Write a test here.

Tips:

  • make test-api-docs runs all API docs tests. This command also builds the derefed JSON. This runs in CI but can be useful for local development to make sure everything passes.
  • yarn run build-derefed-docs builds the derefed JSON. This is useful in the case where you're only running one test locally, making a change to the schema, and then re-running the test. Since the tests run against the derefed version, you'll need to rebuild it.

To see your changes in the docs locally:

In sentry:

  1. Run yarn run watch-api-docs. This command will watch API docs files and continuously build an intermediate asset tests/apidocs/openapi-derefed.json.
  2. Copy the full path to tests/apidocs/openapi-derefed.json.

In sentry-docs:

  1. Run OPENAPI_LOCAL_PATH=COPIED_FULL_PATH DISABLE_THUMBNAILS=1 yarn start and substitute COPIED_FULL_PATH with the copied path to your local openapi-derefed.json

When you open the pull request, please add a screenshot of the page or pages you're adding.

Build process

The openapi-diff test will fail when CI runs on your pull request, this is expected and meant to highlight the diff. It is not required to merge.

Once you make changes to an endpoint and merge the change into Sentry, a series of GitHub Actions will be triggered to make your changes automatically go live:

  1. The openapi / deref_json GitHub Action in sentry will update the schema in sentry-api-schema with the OpenAPI build artifact.
  2. In sentry-api-schema, the sentry-docs / bump GitHub Action will be triggered and this will bump the SHA that references sentry-api-schema in sentry-docs with the latest.
  3. Finally, a build is triggered in sentry-docs.

Requesting an API to be public

Want an endpoint to be public?

Look at the issues on sentry with the Component: API label. If a request has already been made to make the endpoint public, give it a thumbs up. If not, create a feature request on Sentry and add the Component: API label.

The team responsible for the endpoint will review the stability of the endpoint. If the endpoint will not have breaking changes in future, they can determine whether to make it public.

FAQs

When should an attribute be required?

An attribute is required if it will always be returned by the API.

What does it mean when a response doesn't have a schema?

Some endpoints have no response schema. This means that while the endpoint is public, the attributes within that endpoint can change at any time. This is a relic from migrating the documentation from our prior approach. Note that, going forward, we recommend new endpoints always provide response schema.

I have a question and it has not been answered.

No problem. Send us an email so we can answer your question.

Can customers use private endpoints?

Yes, if they wish. However, private endpoints can change at any time, without notice. As a result, the customer's code could break.

You can edit this page on GitHub.