Apply suggestions from code review

apply suggested changes

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

src/docs/api/basics.mdx

@@ -2,15 +2,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.
+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 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.
+- **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
-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 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/design.mdx

@@ -5,23 +5,22 @@ 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.
+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 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. 
+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/
-```
+- 👍 `/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/)|
+| 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,7 @@
 title: 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.
+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/)