Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.

Commit 2bfe62a

Browse files
author
Manu
authored
feat(api): Add API checklist and API concepts (#404)
* feat(api): Add API checklist and API concepts * API concepts words changes * CR comments * Make project slug consistent
1 parent f95ec5c commit 2bfe62a

File tree

5 files changed

+129
-8
lines changed

5 files changed

+129
-8
lines changed

‎src/components/sidebar.tsx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,7 @@ export default () => {
3737
<SidebarLink to="https://github.com/getsentry/.github/blob/master/CODE_OF_CONDUCT.md">
3838
Code of Conduct
3939
</SidebarLink>
40-
<SidebarLink to="/docs/" title="Documentation Guide">
41-
<SidebarLink to="/docs/api/">Making an API Public</SidebarLink>
42-
</SidebarLink>
40+
<SidebarLink to="/docs/">Documentation Guide</SidebarLink>
4341
<SidebarLink to="/inclusion/">Inclusive Language</SidebarLink>
4442
<SidebarLink to="/translations/">Translations</SidebarLink>
4543
<SidebarLink to="/code-review/">Code Review</SidebarLink>
@@ -87,6 +85,11 @@ export default () => {
8785
<SidebarLink to="/config/">Configuration</SidebarLink>
8886
<SidebarLink to="/feature-flags/">Feature Flags</SidebarLink>
8987
<SidebarLink to="/serializers/">Serializers</SidebarLink>
88+
<SidebarLink to="/api/" title="API">
89+
<Children
90+
tree={tree.find(n => n.name === "api").children}
91+
/>
92+
</SidebarLink>
9093
<SidebarLink to="/pii/" title="PII and Data Scrubbing">
9194
<SidebarLink to="/pii/types/">Rule Types</SidebarLink>
9295
<SidebarLink to="/pii/methods/">Redaction Methods</SidebarLink>

‎src/docs/api/checklist.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: "Public API Checklist"
3+
---
4+
5+
Below is a checklist that developers should go through before making APIs public.
6+
7+
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.
8+
1. The API should be available if requested with a bearer token from the integration platform.
9+
1. There are scopes that can be selected in the integration platform that enables or disables access to the resource exposed by the API.
10+
1. 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.
11+
1. APIs returning a variable number of elements as a list should be paginated. They should be paginated using the link header standard.
12+
1. End user requests should not easily be able to trigger 5xx errors in our application by manipulating request data or sending invalid/malformed data.
13+
1. 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.
14+
1. 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.
15+
1. 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.

‎src/docs/api/concepts.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: "API Concepts"
3+
---
4+
In this document, we will be looking at API concepts that exist and should be followed by endpoints. We also describe why these concepts exist so that developers can use them at their own discretion.
5+
6+
## Expanding responses
7+
Expanding responses allow us to include relational information on a resource without loading it by default.
8+
9+
In general, endpoints should expose the fewest fields that will make the API usable in the general scenario. Doing one SQL request per API request is a good rule of thumb. To return information on a bounded relationship, endpoints should rely on the `expand` parameter. To return an unbounded relationship, it should be another endpoint.
10+
11+
To take an example, let's talk about the projects list endpoint. A project belongs to an organizations but could be on multiple teams.
12+
13+
By default, here's what the project endpoint should look like
14+
15+
```json
16+
GET /api/0/projects/{project_slug}/
17+
{
18+
"id": 5,
19+
"name": "foo",
20+
...
21+
}
22+
```
23+
24+
To display information about a bounded relationship, a user should be able to use the `expand` parameter. This is generally only true for 1:1 relationships.
25+
26+
```json
27+
GET /api/0/projects/{project_slug}/?expand=organization
28+
{
29+
"id": 5,
30+
"name": "foo",
31+
"organization": {
32+
"slug": "bar",
33+
"isEarlyAdopter": false,
34+
...
35+
}
36+
...
37+
}
38+
```
39+
40+
For unbounded relationships, make a separate query. This allows the query to be paginated and reduces the risk of having an arbitrarily large payload.
41+
42+
```json
43+
GET /api/0/projects/{project_slug}/teams
44+
[
45+
{
46+
"id": 1,
47+
"name": "Team 1",
48+
"slug": "team1",
49+
},
50+
{
51+
"id": 2,
52+
"name": "Team 2",
53+
"slug": "team2",
54+
}
55+
]
56+
57+
```
58+
59+
## Collapsing responses
60+
Similar to expanding responses, an API endpoint can also collapse responses. When the `collapse` parameter is passed, the API should not return attributes that have been collapsed.
61+
62+
To take an example, let's look at the project list endpoints again. A project gets events and hence, has a `stats` component, which conveys information about how many events were received for the project. Let's say we made the stats part of the endpoint public, along with the rest of the projects list endpoint.
63+
64+
```json
65+
GET /api/0/projects/{project_slug}/
66+
{
67+
"id": 5,
68+
"name": "foo",
69+
"stats": {
70+
"24h": [
71+
[
72+
1629064800,
73+
27
74+
],
75+
[
76+
1629068400,
77+
24
78+
],
79+
...
80+
]
81+
}
82+
}
83+
```
84+
85+
The `collapse` parameter can be passed to not return stats information.
86+
87+
```json
88+
GET /api/0/projects/{project_slug}/?collapse=stats
89+
{
90+
"id": 5,
91+
"name": "foo",
92+
...
93+
}
94+
```
95+
96+
This is typically only needed if the endpoint is already public and we do not want to introduce a breaking change. Remember, if the endpoint is public and we remove an attribute, it is a breaking change. If you are iterating on an undocumented endpoint, return the minimal set of attributes and rely on the `expand` parameter to get more detailed information.

‎src/docs/api/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: API
3+
---
4+
5+
Welcome to the land of APIs! Here, we talk about all things API:
6+
- [API Concepts](/api/concepts/)
7+
- [Making an API Public](/api/public/)
8+
- [Public API checklist](/api/checklist/)

src/docs/docs/api.mdx renamed to src/docs/api/public.mdx

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,16 +60,15 @@ Making an API public offers considerable benefits. A public API allows our custo
6060

6161
As a guide, use these questions:
6262

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

67-
If your answers are Yes, No and Yes, you're in business - make the API public.
66+
If your answers are Yes and No, you're in business - make the endpoint public. Head over to the [public API checklist](/api/checklist/) and ensure that your endpoint conforms to the checklist.
6867

6968
## How to make an endpoint public?
7069

71-
We use [Open API Spec 3](https://swagger.io/docs/specification/about/) to write our API documentation.
72-
You can find that content here: [https://github.com/getsentry/sentry/tree/master/api-docs.](https://github.com/getsentry/sentry/tree/master/api-docs)
70+
We use [Open API Spec 3](https://swagger.io/docs/specification/about/) to write our API documentation.
71+
You can find that content here: [https://github.com/getsentry/sentry/tree/master/api-docs.](https://github.com/getsentry/sentry/tree/master/api-docs)
7372
You can find the tests here: [https://github.com/getsentry/sentry/tree/master/tests/apidocs](https://github.com/getsentry/sentry/tree/master/tests/apidocs).
7473

7574
### Local development

0 commit comments

Comments
 (0)