docs(apis): Adding API basics

src/docs/api/basics.mdx

@@ -0,0 +1,16 @@
+---
+title: "REST API Basics"
+sidebar_order: 1
+---
+This session includes some common terms we will be using as well as 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 event ID or slug like organization slug. Note that it has to be unique for example Sentry project resource identifier is {org_slug}/{project_slug} because projects are only unique within their organization. We will explain more in 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
+In this guide we will include the standards that Sentry follows to design high quality APIs but if you want to learn more about API design in general, here are some good recources:
+- **[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,27 @@
+---
+title: "Designing a New API"
+sidebar_order: 2
+---
+Here are some considerations to make when designing new Sentry APIs. 
+
+## URL Patterns
+Your API URL is what developers use to call the endpoint so it’s important to be 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 but they can also make the URLs too long and hard to use. So at Sentry we’re going with 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} | [Creat a New Team](https://docs.sentry.io/api/teams/create-a-new-team/) |
+| teams | Whenever resource is under a specific team in hierarchy | organizations | {organization_slug}/ {team_slug} | [Retreive Team Stats](https://docs.sentry.io/api/teams/retrieve-event-counts-for-a-team/) | 
+| projects | When resource is under a specific project in 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 resource is under a specific issue in hierarchy | projects | {issue_id} | [List an Issue's Events](https://docs.sentry.io/api/events/list-an-issues-events/)|
+| sentry-app-installations | When 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 and be able to do their key needs without going to the UI. If you’re creating an endpoint or editing one this doc can be a guide on how to 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