Add information about choosing which API to use (github#30781)

Co-authored-by: Lucas Costi <[email protected]>

Author: skedwards88

content/developers/index.md

@@ -11,11 +11,11 @@ featuredLinks:
     - /developers/apps/building-github-apps/authenticating-with-github-apps
     - /developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps
   popular:
+    - /developers/overview/about-githubs-apis
     - /developers/webhooks-and-events/webhooks/webhook-events-and-payloads
     - /developers/apps/building-github-apps/creating-a-github-app
     - /developers/apps/building-github-apps/authenticating-with-github-apps
     - /developers/webhooks-and-events/webhooks/about-webhooks
-    - /developers/apps/building-oauth-apps/creating-an-oauth-app
     - /developers/apps/building-oauth-apps/authorizing-oauth-apps
     - /developers/github-marketplace/github-marketplace-overview/about-github-marketplace
   guideCards:

content/developers/overview/about-githubs-apis.md

@@ -14,4 +14,72 @@ topics:
   - API
 ---
 
-There are two stable versions of the GitHub API: the [REST API](/rest) and the [GraphQL API](/graphql).
+## About {% data variables.product.company_short %}'s APIs
+
+{% data variables.product.company_short %} provides two APIs: a REST API and a GraphQL API. You can interact with both APIs using {% data variables.product.prodname_cli %}, curl, the official Octokit libraries, and third party libraries. Occasionally, a feature may be supported on one API but not the other.
+
+You should choose the API that best aligns with your needs and that you are most comfortable using. This article discusses the benefits of each API.
+
+For more information about the GraphQL API, see [the GraphQL documentation](/graphql). For more information about the REST API, see [the REST documentation](/rest).
+
+## Choosing the GraphQL API
+
+The GraphQL API returns exactly the data that you request. GraphQL also returns the data in a pre-known structure based on your request. In contrast, the REST API returns more data than you requested and returns it in a pre-determined structure. You can also accomplish the equivalent of multiple REST API request in a single GraphQL request. The ability to make fewer requests and fetch less data makes GraphQL appealing to developers of mobile applications.
+
+For example, to get the {% data variables.product.product_name %} login of ten of your followers, and the login of ten followers of each of your followers, you can send a single request like:
+
+```graphql
+{
+  viewer {
+    followers(first: 10) {
+      nodes {
+        login
+        followers(first: 10) {
+          nodes {
+            login
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The response will be a JSON object that follows the structure of your request.
+
+In contrast, to get this same information from the REST API, you would need to first make a request to `GET /user/followers`. The API would return the login of each follower, along with other data about the followers that you don't need. Then, for each follower, you would need to make a request to `GET /users/{username}/followers`. In total, you would need to make 11 requests to get the same information that you could get from a single GraphQL request, and you would receive excess data.
+
+## Choosing the REST API
+
+Because REST APIs have been around for longer than GraphQL APIs, some developers are more comfortable with the REST API. Since REST APIs use standard HTTP verbs and concepts, many developers are already familiar with the basic concepts to use the REST API.
+
+For example, to create an issue in the `octocat/Spoon-Knife` repository, you would need to send a request to `POST /repos/octocat/Spoon-Knife/issues` with a JSON request body:
+
+```json
+{
+  "title": "Bug with feature X",
+  "body": "If you do A, then B happens"
+}
+```
+
+In contrast, to make an issue using the GraphQL API, you would need to get the node ID of the `octocat/Spoon-Knife` repository and then send a request like:
+
+```graphql
+mutation {
+  createIssue(
+    input: {
+      repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
+      title: "Bug with feature X"
+      body: "If you do A, then B happens"}
+  ) {
+    issue {
+      number
+      url
+    }
+  }
+}
+```
+
+## Choosing both
+
+You don't need to exclusively use one API over the other. Node IDs let you move between the REST API and GraphQL API. For more information, see "[Using global node IDs](/graphql/guides/using-global-node-ids)."

content/graphql/guides/migrating-from-rest-to-graphql.md

@@ -16,6 +16,8 @@ shortTitle: Migrate from REST to GraphQL
 
 ## Differences in API logic
 
+{% data variables.product.company_short %} provides two APIs: a REST API and a GraphQL API. For more information about {% data variables.product.company_short %}'s APIs, see "[About {% data variables.product.company_short %}'s APIs](/developers/overview/about-githubs-apis)."
+
 Migrating from REST to GraphQL represents a significant shift in API logic. The differences between REST as a style and GraphQL as a specification make it difficult—and often undesirable—to replace REST API calls with GraphQL API queries on a one-to-one basis. We've included specific examples of migration below.
 
 To migrate your code from the [REST API](/rest) to the GraphQL API:

content/graphql/overview/about-the-graphql-api.md

@@ -20,6 +20,8 @@ Here are some quick links to get you up and running with the GraphQL API:
 * [Rate limits](/graphql/overview/resource-limitations)
 * [Migrating from REST](/graphql/guides/migrating-from-rest-to-graphql)
 
+For more information about {% data variables.product.company_short %}'s APIs, see "[About {% data variables.product.company_short %}'s APIs](/developers/overview/about-githubs-apis)."
+
 ## About GraphQL
 
 The [GraphQL](https://graphql.github.io/) data query language is:

content/rest/guides/getting-started-with-the-rest-api.md

@@ -20,6 +20,8 @@ When you make a request to the REST API, you will specify an HTTP method and a p
 
 The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation. For more information, see the [REST reference documentation](/rest).
 
+For more information about {% data variables.product.company_short %}'s APIs, see "[About {% data variables.product.company_short %}'s APIs](/developers/overview/about-githubs-apis)."
+
 ## Making a request
 
 To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "Get Octocat" operation uses the `GET` method and the `/octocat` path. For the full reference documentation for this operation, see "[Get Octocat](/rest/meta#get-octocat)."