docs(apis): Adding API basics (#1027)

* docs(apis): Adding API basics

* Apply suggestions from code review

apply suggested changes

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

---------

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

src/docs/api/basics.mdx

@@ -0,0 +1,17 @@
+---
+title: "REST API Basics"
+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.
+- **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
+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.

src/docs/api/checklist.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Public API Checklist"
+sidebar_order: 5
 ---
 
 Below is a checklist that developers should go through before making APIs public.

src/docs/api/concepts.mdx

@@ -1,5 +1,6 @@
 ---
 title: "API Concepts"
+sidebar_order: 3
 ---
 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.
 

src/docs/api/design.mdx

@@ -0,0 +1,26 @@
+---
+title: "Designing a New API"
+sidebar_order: 2
+---
+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](https://docs.sentry.io/api/teams/create-a-new-team/) |
+| teams | When the resource is under a specific team in the hierarchy | organizations | {organization_slug}/ {team_slug} | [Retreive Team Stats](https://docs.sentry.io/api/teams/retrieve-event-counts-for-a-team/) | 
+| 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](https://docs.sentry.io/api/projects/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](https://docs.sentry.io/api/events/list-an-issues-events/)|
+| sentry-app-installations | When the resource is mapped to a specific integration | organizations | {integration_slug} | [Delete an External Issue](https://docs.sentry.io/api/integration/delete-an-external-issue/)|

src/docs/api/index.mdx

@@ -2,7 +2,9 @@
 title: API
 ---
 
-Welcome to the land of APIs! Here, we talk about all things API:
+As a developer-facing company it’s critical for us to have simple, intuitive, and consistent APIs that our users can call from their dev environment to accomplish key tasks without going to the UI. If you’re creating or editing an endpoint, this doc will help you achieve Sentry standards.
+- [REST API Basics](/api/basics/)
+- [Desiging a New API](/api/design/)
 - [API Concepts](/api/concepts/)
 - [Making an API Public](/api/public/)
 - [Public API checklist](/api/checklist/)

src/docs/api/public.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Making an API Public'
+sidebar_order: 4
 ---
 
 ## Introduction