From e7b5b77a81f513ec04c495a82d615a855bef3b02 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Thu, 28 Apr 2022 09:59:56 -0700 Subject: [PATCH 1/2] Update frontmatter and intro info for the singleton API pages (#27236) Co-authored-by: hubwriter --- content/rest/billing.md | 4 +++- content/rest/code-scanning.md | 4 +++- content/rest/codes-of-conduct.md | 8 +++++--- content/rest/deploy-keys.md | 6 ++++-- content/rest/gitignore.md | 2 ++ content/rest/licenses.md | 2 ++ content/rest/oauth-authorizations.md | 6 ++++-- content/rest/packages.md | 2 ++ content/rest/rate-limit.md | 4 +++- content/rest/reactions.md | 4 ++-- content/rest/scim.md | 2 ++ content/rest/search.md | 4 +++- content/rest/secret-scanning.md | 6 ++++-- 13 files changed, 39 insertions(+), 15 deletions(-) diff --git a/content/rest/billing.md b/content/rest/billing.md index 6f9ccd86a6..e1268390e9 100644 --- a/content/rest/billing.md +++ b/content/rest/billing.md @@ -1,6 +1,6 @@ --- title: Billing -intro: '' +intro: 'The Billing API lets you get billing information for an enterprise.' topics: - API miniTocMaxHeadingLevel: 3 @@ -12,4 +12,6 @@ redirect_from: - /rest/reference/billing --- +## About the Billing API + You can get billing information for an enterprise. For more information, see the "[{% data variables.product.prodname_dotcom %} Enterprise administration](/rest/reference/enterprise-admin#billing)" REST API. \ No newline at end of file diff --git a/content/rest/code-scanning.md b/content/rest/code-scanning.md index 8c464645a9..39cb2c607c 100644 --- a/content/rest/code-scanning.md +++ b/content/rest/code-scanning.md @@ -1,6 +1,6 @@ --- title: Code Scanning -intro: '' +intro: 'The {% data variables.product.prodname_code_scanning %} API lets you retrieve and update {% data variables.product.prodname_code_scanning %} alerts from a repository.' versions: fpt: '*' ghes: '*' @@ -17,6 +17,8 @@ redirect_from: {% data reusables.code-scanning.beta %} +## About the Code scanning API + The {% data variables.product.prodname_code_scanning %} API lets you retrieve and update {% data variables.product.prodname_code_scanning %} alerts from a repository. You can use the endpoints to create automated reports for the {% data variables.product.prodname_code_scanning %} alerts in an organization or upload analysis results generated using offline {% data variables.product.prodname_code_scanning %} tools. For more information, see "[Finding security vulnerabilities and errors in your code](/github/finding-security-vulnerabilities-and-errors-in-your-code)." {% ifversion fpt or ghes > 3.0 or ghae or ghec %} diff --git a/content/rest/codes-of-conduct.md b/content/rest/codes-of-conduct.md index dd96f59734..94b3f26c77 100644 --- a/content/rest/codes-of-conduct.md +++ b/content/rest/codes-of-conduct.md @@ -1,6 +1,6 @@ --- -title: Codes of Conduct -intro: '' +title: Codes of conduct +intro: "The Codes of conduct API lets you retrieve information about a repository's code of conduct." versions: fpt: '*' ghes: '*' @@ -13,4 +13,6 @@ redirect_from: - /rest/reference/codes-of-conduct --- -You can use the Codes of Conduct API to retrieve information about a repository's code of conduct. To get a repository's code of conduct, use the "[Get a repository](/rest/reference/repos#get-a-repository)" endpoint. \ No newline at end of file +## About the Codes of conduct API + +You can use the Codes of Conduct API to retrieve information about a repository's code of conduct. To get a code of conduct for a repository, use the "[Get a repository](/rest/reference/repos#get-a-repository)" endpoint. \ No newline at end of file diff --git a/content/rest/deploy-keys.md b/content/rest/deploy-keys.md index 0158b1194b..337c17fc71 100644 --- a/content/rest/deploy-keys.md +++ b/content/rest/deploy-keys.md @@ -1,6 +1,6 @@ --- -title: Deploy Keys -intro: '' +title: Deploy keys +intro: 'The Deploy keys API lets you create and manage deploy keys.' versions: fpt: '*' ghes: '*' @@ -14,6 +14,8 @@ redirect_from: - /rest/reference/deploy_keys --- +## About the Deploy keys API + {% data reusables.repositories.deploy-keys %} Deploy keys can either be setup using the following API endpoints, or by using GitHub. To learn how to set deploy keys up in GitHub, see "[Managing deploy keys](/developers/overview/managing-deploy-keys)." \ No newline at end of file diff --git a/content/rest/gitignore.md b/content/rest/gitignore.md index 0a641c3994..4155963e74 100644 --- a/content/rest/gitignore.md +++ b/content/rest/gitignore.md @@ -13,6 +13,8 @@ redirect_from: - /rest/reference/gitignore --- +## About the Gitignore API + When you create a new repository on {% ifversion ghae %}{% data variables.product.product_name %}{% else %}{% data variables.product.product_location %}{% endif %} via the API, you can specify a [.gitignore template](/github/getting-started-with-github/ignoring-files) to apply to the repository upon creation. The .gitignore templates API lists and fetches templates from the {% data variables.product.product_name %} [.gitignore repository](https://github.com/github/gitignore). ### Custom media types for gitignore diff --git a/content/rest/licenses.md b/content/rest/licenses.md index 78619bfa73..d8a62103f5 100644 --- a/content/rest/licenses.md +++ b/content/rest/licenses.md @@ -13,6 +13,8 @@ redirect_from: - /rest/reference/licenses --- +## About the Licenses API + The Licenses API uses [the open source Ruby Gem Licensee](https://github.com/benbalter/licensee) to attempt to identify the project's license. Licensee matches the contents of a project's `LICENSE` file (if it exists) against a short list of known licenses. As a result, the API does not take into account the licenses of project dependencies or other means of documenting a project's license such as references to the license name in the documentation. If a license is matched, the license key and name returned conforms to the [SPDX specification](https://spdx.org/). diff --git a/content/rest/oauth-authorizations.md b/content/rest/oauth-authorizations.md index 2f6e8fab75..a600275fc4 100644 --- a/content/rest/oauth-authorizations.md +++ b/content/rest/oauth-authorizations.md @@ -1,6 +1,6 @@ --- -title: OAuth Authorizations -intro: 'The Migrations API is only available to authenticated organization owners.' +title: OAuth authorizations +intro: 'The OAuth authorizations lets you manage the access OAuth applications have to your account.' versions: fpt: '*' ghec: '*' @@ -12,6 +12,8 @@ redirect_from: - /rest/reference/oauth-authorizations --- +## About the OAuth authorizations API + You can use this API to manage the access OAuth applications have to your account. You can only access this API via [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) using your username and password, not tokens. If you or your users have two-factor authentication enabled, make sure you understand how to [work with two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication). \ No newline at end of file diff --git a/content/rest/packages.md b/content/rest/packages.md index 32204571ad..f21db595d7 100644 --- a/content/rest/packages.md +++ b/content/rest/packages.md @@ -11,6 +11,8 @@ redirect_from: - /rest/reference/packages --- +## About the {% data variables.product.prodname_registry %} API + The {% data variables.product.prodname_registry %} API enables you to manage packages using the REST API.{% ifversion fpt or ghec or ghes > 3.1 or ghae %} To learn more about restoring or deleting packages, see "[Restoring and deleting packages](/packages/learn-github-packages/deleting-and-restoring-a-package)."{% endif %} To use this API, you must authenticate using a personal access token. diff --git a/content/rest/rate-limit.md b/content/rest/rate-limit.md index 502ba87c86..2c88f7a89f 100644 --- a/content/rest/rate-limit.md +++ b/content/rest/rate-limit.md @@ -1,6 +1,6 @@ --- title: Rate limit -intro: 'With the Rate Limit API, you can check the current rate limit status of various REST APIs.' +intro: 'With the Rate limit API, you can check the current rate limit status of various REST APIs.' versions: fpt: '*' ghes: '*' @@ -13,6 +13,8 @@ redirect_from: - /rest/reference/rate-limit --- +## About the Rate limit API + The REST API overview documentation describes the [rate limit rules](/rest/overview/resources-in-the-rest-api#rate-limiting). You can check your current rate limit status at any time using the Rate Limit API described below. ### Understanding your rate limit status diff --git a/content/rest/reactions.md b/content/rest/reactions.md index 6ba29b6b1d..3e752e5820 100644 --- a/content/rest/reactions.md +++ b/content/rest/reactions.md @@ -13,8 +13,8 @@ redirect_from: - /rest/reference/reactions --- -### Reaction types +## About the Reactions API -When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): +You can create and manage reactions on comments using the Reactions API. When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): {% data reusables.repositories.reaction_list %} \ No newline at end of file diff --git a/content/rest/scim.md b/content/rest/scim.md index f697c0644f..7e7554d03f 100644 --- a/content/rest/scim.md +++ b/content/rest/scim.md @@ -11,6 +11,8 @@ redirect_from: - /rest/reference/scim --- +## About the SCIM API + ### SCIM Provisioning for Organizations The SCIM API is used by SCIM-enabled Identity Providers (IdPs) to automate provisioning of {% data variables.product.product_name %} organization membership. The {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API is based on version 2.0 of the [SCIM standard](http://www.simplecloud.info/). The {% data variables.product.product_name %} SCIM endpoint that an IdP should use is: `{% data variables.product.api_url_code %}/scim/v2/organizations/{org}/`. diff --git a/content/rest/search.md b/content/rest/search.md index a463da9363..cc5712aeee 100644 --- a/content/rest/search.md +++ b/content/rest/search.md @@ -1,6 +1,6 @@ --- title: Search -intro: 'The GitHub Search API lets you to search for the specific item efficiently.' +intro: 'The Search API lets you to search for specific items on {% data variables.product.product_name %}.' versions: fpt: '*' ghes: '*' @@ -13,6 +13,8 @@ redirect_from: - /rest/reference/search --- +## About the Search API + The Search API helps you search for the specific item you want to find. For example, you can find a user or a specific file in a repository. Think of it the way you think of performing a search on Google. It's designed to help you find the one result you're looking for (or maybe the few results you're looking for). Just like searching on Google, you sometimes want to see a few pages of search results so that you can find the item that best meets your needs. To satisfy that need, the {% data variables.product.product_name %} Search API provides **up to 1,000 results for each search**. You can narrow your search using queries. To learn more about the search query syntax, see "[Constructing a search query](/rest/reference/search#constructing-a-search-query)." diff --git a/content/rest/secret-scanning.md b/content/rest/secret-scanning.md index fad846994e..a5d40f1a39 100644 --- a/content/rest/secret-scanning.md +++ b/content/rest/secret-scanning.md @@ -1,6 +1,6 @@ --- -title: Secret Scanning -intro: 'Use the Secret Scanning API to retrieve and update secret alerts from a repository.' +title: Secret scanning +intro: 'Use the Secret scanning API to retrieve and update secret alerts from a repository.' versions: ghes: '*' ghae: '*' @@ -14,6 +14,8 @@ redirect_from: {% data reusables.secret-scanning.api-beta %} +## About the Secret scanning API + The {% data variables.product.prodname_secret_scanning %} API lets you{% ifversion fpt or ghec or ghes > 3.1 or ghae %}: - Enable or disable {% data variables.product.prodname_secret_scanning %}{% if secret-scanning-push-protection %} and push protection{% endif %} for a repository. For more information, see "[Repositories](/rest/reference/repos#update-a-repository)" and expand the "Properties of the `security_and_analysis` object" section in the REST API documentation. From 0d1b70548c83f4f7ce1791169247e53ca4aa58c4 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Thu, 28 Apr 2022 10:05:59 -0700 Subject: [PATCH 2/2] update intros (#27297) --- content/rest/commits/comments.md | 6 +++++- content/rest/commits/statuses.md | 6 ++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/content/rest/commits/comments.md b/content/rest/commits/comments.md index 34ff1e9f90..17a3f28c32 100644 --- a/content/rest/commits/comments.md +++ b/content/rest/commits/comments.md @@ -1,6 +1,6 @@ --- title: Commit comments -intro: '' +intro: 'The Commit comments API lets you create and edit comments that relate to specific commits.' versions: fpt: '*' ghes: '*' @@ -12,6 +12,10 @@ miniTocMaxHeadingLevel: 3 allowTitleToDifferFromFilename: true --- +## About the commit comments API + +The Commit comments API lets you create and edit comments that relate to specific commits. + ### Custom media types for commit comments These are the supported media types for commit comments. You can read more diff --git a/content/rest/commits/statuses.md b/content/rest/commits/statuses.md index 27050e2439..9f429cfbdf 100644 --- a/content/rest/commits/statuses.md +++ b/content/rest/commits/statuses.md @@ -1,6 +1,6 @@ --- title: Commit statuses -intro: 'The status API allows external services to mark commits with an `error`, `failure`, `pending`, or `success` state, which is then reflected in pull requests involving those commits.' +intro: 'The Commit status API allows external services to mark commits with a status, which is then reflected in pull requests involving those commits.' versions: fpt: '*' ghes: '*' @@ -12,7 +12,9 @@ miniTocMaxHeadingLevel: 3 allowTitleToDifferFromFilename: true --- -Statuses can also include an optional `description` and `target_url`, and we highly recommend providing them as they make statuses much more useful in the GitHub UI. +## About the Commit statuses API + +The Commit status API allows external services to mark commits with an `error`, `failure`, `pending`, or `success` state, which is then reflected in pull requests involving those commits. Statuses can also include an optional `description` and `target_url`, and we highly recommend providing them as they make statuses much more useful in the GitHub UI. As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. The `target_url` would be the full URL to the build output, and the `description` would be the high level summary of what happened with the build.