Merge branch 'master' of github.com:getsentry/sentry-docs into smi/quick-start/review-nestjs

Author: inventarSarah

data-schemas

@@ -31,8 +31,8 @@ Use the following guidelines for naming resources and their collections:
 
 - **Do** use lowercase and hyphenated collection names, e.g. `commit-files`.
 - **Do** use plural collection names. Avoid using uncountable words because the user can't know whether the GET returns one item or a list.
-- **Do** use `snake_case` for path parameters. e.g. `tags/\{tag_name}/`.
-- **Do** consistently shorten parameters that are excessively long when the term will unambiguous. e.g. `organization` -> `org`.
+- **Do** use `snake_case` for path parameters. e.g. `tags/{tag_name}/`.
+- **Do** consistently shorten parameters that are excessively long when the term is unambiguous. e.g. `organization` -> `org`.
 
 Standard path parameters that should be shortened in routes:
 
@@ -42,8 +42,8 @@ Standard path parameters that should be shortened in routes:
 
 Information in Sentry is typically constrained by tenants. That is, almost all information is scoped to an organization. All endpoints which query customer data **must** be scoped to an organization:
 
-- **Do** prefix resource organizations collections with `organizations/\{org}`.
-- **Do** prefix resource project collections with `projects/\{org}/\{project}`.
+- **Do** prefix organization resource collections with `/organizations/{org}/`.
+- **Do** prefix project resource collections with `/projects/{org}/{project}/`.
 - **Do not** expose endpoints which require `org` as a query parameter (it should always be a path parameter).
 
 Knowing when to choose which constraint to couple an endpoint to will be based on the purpose of an endpoint. For example, if an endpoint is only ever going to be used to query data for a single project, it should be prefixed with `/projects/{org}/{project}/things`. If an endpoint would need to exist to query multiple projects (which is common with cross-project queries), you likely should expose it as `/organizations/{org}/things`, and expose a query param to filter on the project(s).
@@ -57,34 +57,34 @@ Exceptions to these rules include:
 
 **Do not** exceed three levels of resource nesting.
 
-Nesting resources such as `/organizations/\{org}/projects/`, is **preferred** over flattened resources like `/0/projects/`. This improves readability and exposes a natural understanding of resource hierarchy and relationships. However, nesting can make URLs too long and hard to use. Sentry uses 3-level nesting as a hybrid solution.
+Nesting resources such as `/organizations/{org}/projects/`, is **preferred** over flattened resources like `/0/projects/`. This improves readability and exposes a natural understanding of resource hierarchy and relationships. 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/\{org}/\{project}/tags/\{tag}/values`
-- 👎 `/organizations/\{org}/projects/\{project}/tags/\{tag}/values/`
+- 👍 `/projects/{org}/{project}/tags/{tag}/values`
+- 👎 `/organizations/{org}/projects/{project}/tags/{tag}/values/`
 - 👎 `/values/`
 
 Hierarchy here does not necessarily mean that one collection belongs to a parent collection, it simply implies a relationship. For example:
 
-- `projects/\{project_identifier}/teams/` refers to the **teams** that have been added to specific project
-- `teams/\{team_identifier}/projects/` refers to the **projects** a specific team has been added to
+- `/projects/{project_identifier}/teams/` refers to the **teams** that have been added to specific project
+- `/teams/{team_identifier}/projects/` refers to the **projects** a specific team has been added to
 
 ## Parameter Design
 
 - **Do** use `camelCase` for query params and request body params. e.g. `/foo/?userId=123`.
-- **Do** use `camelCase` for all response attributes. e.g. `\{userId: "123"}`.
+- **Do** use `camelCase` for all response attributes. e.g. `{userId: "123"}`.
 
 For consistency, we also try to re-use well known parameters across endpoints.
 
-- **Do** use `sortBy` for sorting. e.g. `sortBy=-dateCreated`.
-- **Do** use `orderBy` for ordering. e.g. `orderBy=asc` or `orderBy=desc`.
-- **Do** use `limit` for limiting the number of results returned. e.g. `limit=10`.
+- **Do** use `sortBy` for sorting. e.g. `?sortBy=-dateCreated`.
+- **Do** use `orderBy` for ordering. e.g. `?orderBy=asc` or `?orderBy=desc`.
+- **Do** use `limit` for limiting the number of results returned. e.g. `?limit=10`.
 - **Do** use `cursor` for pagination.
 
 ### Resource Identifiers
 
-Identifiers exist both within the route (`/organizations/\{organization}/projects/`) as well as within other parameters such as query strings (`organization=123`) and request bodies (`\{organization: "123"}`).
+Identifiers exist both within the route (`/organizations/{organization}/projects/`) as well as within other parameters such as query strings (`?organization=123`) and request bodies (`{organization: "123"}`).
 
 The most important concern here is to ensure that a single identifier is exposed to key to resources. For example, it is preferred to use `organization` and accept both `organization_id` and `organization_slug` as valid identifiers.
 
@@ -119,24 +119,24 @@ POST /resources/{id}
 
 ### Batch Operations
 
-Resources can get complicated when you need to expose batch operations vs single resource operations. For batch operations it it is preferred to expose them as a `POST` request on the collection when possible.
+Resources can get complicated when you need to expose batch operations vs single resource operations. For batch operations it is preferred to expose them as a `POST` request on the collection when possible.
 
 Let's say for example we have an endpoint that mutates an issue:
 
 ```
-POST /api/0/organizations/:org/issues/:issue/
+POST /api/0/organizations/{org}/issues/{issue}/
 ```
 
 When designing a batch interface, we simply expose it on the collection instead of the individual resource:
 
 ```
-POST /api/0/organizations/:org/issues/
+POST /api/0/organizations/{org}/issues/
 ```
 
 You may also need to expose selectors on batch resources, which can be done through normal request parameters:
 
 ```
-POST /api/0/organizations/:org/issues/
+POST /api/0/organizations/{org}/issues/
 {
   "issues": [1, 2, 3]
 }
@@ -166,7 +166,7 @@ Here are some examples of how to use standard methods to represent complex tasks
 
 **Retrieve statistics for a resource**
 
-The best approach here is to encoded it as an attribute in the resource:
+The best approach here is to encode it as an attribute in the resource:
 
 ```
 GET /api/0/projects/{project}/
@@ -182,7 +182,7 @@ In some cases this will be returned as part of an HTTP header, specifically for
 
 Order and filtering should happen as part of list api query parameters. Here's a [good read](https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/).
 
-- **Do** rely on `orderBy` and `sortBy`. e.g. `/api/0/issues/\{issue_id}/events?orderBy=-date`
+- **Do** rely on `orderBy` and `sortBy`. e.g. `/api/0/issues/{issue_id}/events?orderBy=-date`
 - **Do not** create dedicated routes for these behaviors.
 
 ## Responses
@@ -191,13 +191,13 @@ Each response object returned from an API should be a serialized version of the
 
 Some guidelines around the shape of responses:
 
-- **Do** use `camelCase` for all response attributes. e.g. `\{numCount: "123"}`.
-- **Do** return a responses as a named resource (e.g. `\{"user": \{"id": "123"}}`).
-- **Do** indicate collections using plural nouns (e.g. `\{"users": []}`).
+- **Do** use `camelCase` for all response attributes. e.g. `{"numCount": "123"}`.
+- **Do** return a responses as a named resource (e.g. `{"user": {"id": "123"}}`).
+- **Do** indicate collections using plural nouns (e.g. `{"users": []}`).
 - **Do not** return custom objects. **Do** use a `Serializer` to serialize the resource.
 - **Do** return the smallest amount of data necessary to represent the resource.
 
-Additionally because JavaScript is a primary consumer, be mindful of the restrictions are things like numbers. Generally speaking:
+Additionally because JavaScript is a primary consumer, be mindful of the restrictions on things like numbers. Generally speaking:
 
 - **Do** return resource identifiers (even numbers) as strings.
 - **Do** return decimals as strings.
@@ -222,7 +222,7 @@ Whereas our guidelines state it should be nested:
 GET /api/0/projects/{project}/
 {
   "project": {
-    "id": 5,
+    "id": "5",
     "name": "foo",
     ...
   }
@@ -273,13 +273,13 @@ GET /api/0/projects/{project}/teams
 [
   {
     "id": 1,
-		"name": "Team 1",
-		"slug": "team1",
+    "name": "Team 1",
+    "slug": "team1",
   },
-	{
+  {
     "id": 2,
-		"name": "Team 2",
-		"slug": "team2",
+    "name": "Team 2",
+    "slug": "team2",
   }
 ]
 
@@ -297,17 +297,11 @@ GET /api/0/projects/{project}/
   "id": 5,
   "name": "foo",
   "stats": {
-      "24h": [
-          [
-              1629064800,
-              27
-          ],
-          [
-              1629068400,
-              24
-          ],
-          ...
-      ]
+    "24h": [
+        [1629064800, 27],
+        [1629068400, 24],
+        ...
+    ]
   }
 }
 ```
@@ -330,7 +324,9 @@ This is typically only needed if the endpoint is already public and we do not wa
 >> APIs often need to provide collections of data, most commonly in the `List` standard method. However, collections can be arbitrarily sized, and tend to grow over time, increasing lookup time as well as the size of the responses being sent over the wire. This is why it's important for collections to be paginated.
 
 Paginating responses is a [standard practice for APIs](https://google.aip.dev/158), which Sentry follows.
+
 We've seen an example of a `List` endpoint above; these endpoints have two tell-tale signs:
+
 ```json
 GET /api/0/projects/{project}/teams
 [
@@ -347,12 +343,14 @@ GET /api/0/projects/{project}/teams
 ]
 
 ```
+
 1. The endpoint returns an array, or multiple, objects instead of just one.
 2. The endpoint can sometimes end in a plural (s), but more importantly, it does __not__ end in an identifier (`*_slug`, or `*_id`).
 
 To paginate a response at Sentry, you can leverage the [`self.paginate`](https://github.com/getsentry/sentry/blob/24.2.0/src/sentry/api/base.py#L463-L476) method as part of your endpoint.
 `self.paginate` is the standardized way we paginate at Sentry, and it helps us with unification of logging and monitoring.
 You can find multiple [examples of this](https://github.com/getsentry/sentry/blob/24.2.0/src/sentry/api/endpoints/api_applications.py#L22-L33) in the code base. They'll look something like:
+
 ```python
 def get(self, request: Request) -> Response:
     queryset = ApiApplication.objects.filter(

develop-docs/backend/api/design.mdx

@@ -135,11 +135,12 @@ generally prefer that, since it averages the load out over a longer period of ti
 
 ### Indexes
 
-We prefer to create indexes on large existing tables with `CREATE INDEX CONCURRENTLY`. Our migration framework will do this automatically when creating
-a new index. Note that when `CONCURRENTLY` is used we can't run the migration in a transaction, so it's important to use `atomic = False` to run these.
+These are automatically handled by the migration framework, you can just create them on the Django model and generate the migration.
 
 When adding indexes to large tables you should use a `is_post_deployment` migration as creating the index could take longer than the migration statement timeout of 5s.
 
+Note: These are created using `CONCURRENTLY`, so it's important to not set `atomic = True` for migrations that contain indexes. This is disabled by default.
+
 ### Deleting columns
 
 This is complicated due to our deploy process. When we deploy, we run migrations, and then push out the application code, which takes a while. This means that if we just delete a column or model, then code in sentry will be looking for those columns/tables and erroring until the deploy completes. In some cases, this can mean Sentry is hard down until the deploy is finished.
@@ -419,7 +420,7 @@ This second PR will contain only the migration and related boilerplate.
 
 ### Foreign Keys
 
-Creating foreign keys is mostly fine, but for some large/busy tables like `Project`, `Group` it can cause problems due to difficulties in acquiring a lock. You can still create a Django level foreign key though, without creating a database constraint. To do so, set `db_constraint=False` when defining the key.
+Creating foreign keys is mostly fine, but for some large/busy tables like `Project` and `Group` the migration can fail due to difficulties in acquiring a lock on the table. The general procedure here is to retry the migration until it goes through - The migration framework adds a lock acquisition timeout, so it's safe to do this.
 
 ### Renaming Tables
 

develop-docs/backend/application-domains/database-migrations/index.mdx

@@ -84,23 +84,62 @@ devservices up --mode symbolicator
 
 ## Running a dependency locally
 
-If you want to run a dependency locally rather than as a container, you can do so by toggling the runtime to LOCAL.
+You can run a dependency locally instead of as a container by toggling its runtime via the `devservices toggle` command.
 
-For example, if you are running Sentry and want to use your local Snuba, you can do the following:
+### Toggle to local runtime
+
+For example, if you're running Sentry and want to run Snuba **locally** from source, you can toggle Snuba to the local runtime like this:
+
+```shell
+devservices toggle snuba
+```
+
+or you can specify the runtime explicitly:
 
 ```shell
 devservices toggle snuba LOCAL
 ```
 
-This will tell devservices to not bring up snuba and its dependencies, allowing you to run snuba locally instead.
+This tells devservices to treat Snuba as a service that should be started alongside dependent services like Sentry. Dependencies of Snuba, such as Redis, Kafka, and Clickhouse, will still run as containers.
+
+<Alert title="Note">
+  Toggling to LOCAL does not start the dev server for that service. You'll need to start that manually.
+</Alert>
+
+### What happens when you toggle
+
+If Sentry is already running, toggling Snuba to LOCAL will:
+1. Stop Snuba's containers (unless shared by another service)
+2. Start Snuba's non-local dependencies (Redis, Kafka, Clickhouse) as containers
+
+If Sentry is not yet running, the next time `devservices up` is run, Snuba (and any other services you toggle to LOCAL) will be automatically started as local services alongside Sentry.
+
+If you want to bring up Snuba, or other local runtime dependencies in a non-default mode, you can:
+1. Tell devservices to not bring them up automatically by passing the `--exclude-local` flag to `devservices up`.
+2. Bring that mode up manually via `devservices up --mode <mode>` since modes are additive.
+3. Bring that service down and back up again with the new mode.
+
+### Bringing down services with local runtimes
+
+When stopping services with `devservices down`, the default behavior is to stop all services and their dependencies, including dependencies with local runtimes.
+
+If you don't want dependencies with local runtimes to be brought down when bringing down a dependent service, you can pass the `--exclude-local` flag to `devservices down`. This tells devservices to only stop dependencies that are not running with local runtimes.
+
+### Toggle back to containerized runtime
+
+To switch a service back to running in a container, you can do the following:
+
+```shell
+devservices toggle snuba
+```
 
-To toggle the runtime back to using the container, you can do the following:
+Or explicitly specify the runtime:
 
 ```shell
 devservices toggle snuba CONTAINERIZED
 ```
 
-If you don't provide a runtime when toggling, it will toggle to the opposite of the current runtime.
+Replace `snuba` with the name of the service you want to toggle.
 
 ## Migrating data from the deprecated `sentry devservices`
 

develop-docs/development-infrastructure/devservices.mdx

@@ -32,23 +32,53 @@ const organization = OrganizationFixture({access: ['org:admin'], features: ['my-
 render(<Example />, {organization});
 ```
 
-Router context can be overriden in the same way.
+## Testing route changes
+
+When using `render()`, an in-memory router is used, which will react to navigations with `useNavigate()` or interations with `Link` components. If your component relies on the URL, you can define the initial state in `initialRouterConfig`. You can access the current router state by referencing the returned `router` class, as well as navigate programmatically with `router.navigate()`.
 
 ```tsx
-const {organization, router, routerContext} = initializeOrg({
-  organization: {features: ['global-views', 'open-membership']},
-  router: {
+const {router} = render(<TestComponent />, {
+  initialRouterConfig: {
     location: {
-      pathname: '/organizations/org-slug/issues/',
-      query: {environment: 'prod'},
+      pathname: '/foo/',
+      query: {page: '1'},
     },
-    params: {},
   },
 });
 
-render(<Example />, {context: routerContext, organization});
-await userEvent.click(something);
-expect(router.push).toHaveBeenCalledTimes(1);
+// Uses passes in config to set initial location
+expect(router.location.pathname).toBe('/foo');
+expect(router.location.query.page).toBe('1');
+
+// Clicking links goes to the correct location
+await userEvent.click(screen.getByRole('link', {name: 'Go to /bar/'}));
+
+// Can check current route on the returned router
+expect(router.location.pathname).toBe('/bar/');
+
+// Can test manual route changes with router.navigate
+router.navigate('/new/path/');
+router.navigate(-1); // Simulates clicking the back button
+```
+
+If you need to test route param values (as in `useParams()`), the `route` will need to be provided in the config:
+
+```tsx
+function TestComponent() {
+  const {id} = useParams();
+  return <div>{id}</div>;
+}
+
+const {router} = render(<TestComponent />, {
+  initialRouterConfig: {
+    location: {
+      pathname: '/foo/123/',
+    },
+    route: '/foo/:id/',
+  }
+});
+
+expect(screen.getByText('123')).toBeInTheDocument();
 ```
 
 ## Querying