Overhaul and expand API guidelines

The exposed interfaces in the API have unfortunately become far too varied over the years, and part of this can be blamed on our lack of intentional design behind them. It was always implicit: design it like it was before. Unfortunately implicit design doesn't scale as more people work on a system, so this change documents a set of design principles that we can rely on to future proof new APIs, as well as apply to legacy APIs down the road.

Some notable shifts from where we are today:

- All API endpoints must be designed as if its a public API.
- `PATCH` should not be used. It is redundant with `PUT` in our use cases. If you want to "replace a resource" (which is uncommon behavior), you would do it via `POST /resource/:id`.
- Responses should use noun-based nesting on the object vs being flat (e.g. `{project: {...}` vs `{...}` for a project response).
- Identifiers should accept both human-readable identifiers and numeric identifiers. This has regressed quite drastically over the years, both in terms of query params as well as route identifiers.
- Identifiers should use common names (`organization`) rather than ambiguous attributes (`organization_id`).

Refs #13461

Author: dcramer

develop-docs/backend/api/basics.mdx

@@ -5,13 +5,19 @@ sidebar_order: 1
 This section includes common terms and resources to learn more about API design. If you're new to API design, this is a good place to start.
 
 ## Common Terms
+
 - **Resource** is the object you’re performing the action on with your endpoint. For example, in ProjectEndpoint the resource is Project.
-- **Resource Identifier** can be an ID, like an event ID, or slug, like an organization slug. Note that it must be unique. For example, Sentry's project resource identifier is \{org_slug}/\{project_slug}, because projects are only unique within their organization. You can find more information about this in the slug vs. ID section.
+
+- **Resource Identifier** can be an ID, like an event ID, or slug, like an organization slug. Note that it must be unique. For example, Sentry's project resource identifier is \{organization}/\{project}, because projects are only unique within their organization. You can find more information about this in the slug vs. ID section.
+
 - **Method** is what you do with the resource. Each endpoint can have multiple methods. For example in ProjectEndpoint, you can have a GET method that returns details of a specific project.
+
 - **Collection** is basically an object type. You can map them to a Django object type like an Organization or a text object like an error.
 
-## Extra Resources
+## Additional Reading
+
 The following resources are helpful to learn about general API design best practices:
 
 - **[The Design of Web APIs](https://g.co/kgs/R7rXEk)** is an example-packed guide to designing APIs.
+
 - **[API Design Patterns](https://g.co/kgs/Vfnpe5)** is comprehensive guide on key API patterns.