Designing a New API
Here are some considerations to make when designing new Sentry APIs.
URL Patterns
The API's URL is what developers use to call the endpoint so it’s important that it is meaningful and clear.
Don't Exceed 3-level Nesting
Nested resources format like api/0/organizations/{org}/projects/ is recommended over api/0/projects/ for readability because it gives user an understanding of resource hierarchy. However, nesting can make URLs too long and hard to use. Sentry uses 3-level nesting as a hybrid solution.
Here are some possible urls for values with this resource hierarchy: organization -> project -> tag -> value
- 👍
/projects/{organization_slug}/{project_slug}/tags/{tag_id}/values - 👎
/organizations/{organization_slug}/projects/{project_slug}/tags/{tag_id}/values/ - 👎
/values/
In the above example we flattened projects. The table below shows the existing flattened collections which works out with our existing APIs.
| First collection in URL | When to use | Parent | Identifier | Example |
|---|---|---|---|---|
| organizations | When the resource cannot be attached to any other collection below parent like Project | N/A - always comes as first collection | {organization_slug} | Create a New Team |
| teams | When the resource is under a specific team in the hierarchy | organizations | {organization_slug}/ {team_slug} | Retreive Team Stats |
| projects | When the resource is under a specific project in the hierarchy but not under an issue | organizations | {organization_slug}/ {project_slug} | Create a New Client Key |
| issues | When the resource is under a specific issue in the hierarchy | projects | {issue_id} | List an Issue's Events |
| sentry-app-installations | When the resource is mapped to a specific integration | organizations | {integration_slug} | Delete an External Issue |
You can edit this page on GitHub.