reorganize repository apis (github#23728)

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

Author: 3 people

components/article/ArticlePage.tsx

@@ -1,4 +1,6 @@
+import { useState, useEffect } from 'react'
 import { useRouter } from 'next/router'
+import dynamic from 'next/dynamic'
 import cx from 'classnames'
 import { ActionList, Heading } from '@primer/components'
 
@@ -17,6 +19,10 @@ import { ArticleGridLayout } from './ArticleGridLayout'
 import { PlatformPicker } from 'components/article/PlatformPicker'
 import { ToolPicker } from 'components/article/ToolPicker'
 
+const ClientSideRedirectExceptions = dynamic(() => import('./ClientsideRedirectExceptions'), {
+  ssr: false,
+})
+
 // Mapping of a "normal" article to it's interactive counterpart
 const interactiveAlternatives: Record<string, { href: string }> = {
   '/actions/automating-builds-and-tests/building-and-testing-nodejs': {
@@ -79,8 +85,38 @@ export const ArticlePage = () => {
     )
   }
 
+  // We have some one-off redirects for rest api docs
+  // currently those are limited to the repos page, but
+  // that will grow soon as we restructure the rest api docs.
+  // This is a workaround to updating the hardcoded links
+  // directly in the REST API code in a separate repo, which
+  // requires many file changes and teams to sign off.
+  // While the organization is turbulent, we can do this.
+  // Once it's more settled, we can refactor the rest api code
+  // to leverage the OpenAPI urls rather than hardcoded urls.
+  // The code below determines if we should bother loading this redirecting
+  // component at all.
+  // The reason this isn't done at the server-level is because there you
+  // can't possibly access the URL hash. That's only known in client-side
+  // code.
+  const [loadClientsideRedirectExceptions, setLoadClientsideRedirectExceptions] = useState(false)
+  useEffect(() => {
+    const { hash, pathname } = window.location
+    // Today, Jan 2022, it's known explicitly what the pathname.
+    // In the future there might be more.
+    // Hopefully, we can some day delete all of this and no longer
+    // be dependent on the URL hash to do the redirect.
+    if (hash && pathname.endsWith('/rest/reference/repos')) {
+      setLoadClientsideRedirectExceptions(true)
+    }
+  }, [])
+
   return (
     <DefaultLayout>
+      {/* Doesn't matter *where* this is included because it will
+      never render anything. It always just return null. */}
+      {loadClientsideRedirectExceptions && <ClientSideRedirectExceptions />}
+
       <div className="container-xl px-3 px-md-6 my-4">
         <ArticleGridLayout
           topper={<ArticleTitle>{title}</ArticleTitle>}

components/article/ClientsideRedirectExceptions.tsx

@@ -0,0 +1,35 @@
+import { useEffect } from 'react'
+import { useRouter } from 'next/router'
+
+import overrides from '../../lib/redirects/static/rest-api-redirect-exceptions.json'
+const overrideRedirects: Record<string, string> = overrides
+
+export default function ClientSideRedirectExceptions() {
+  const router = useRouter()
+  useEffect(() => {
+    // We have some one-off redirects for rest api docs
+    // currently those are limited to the repos page, but
+    // that will grow soon as we restructure the rest api docs.
+    // This is a workaround to updating the hardcoded links
+    // directly in the REST API code in a separate repo, which
+    // requires many file changes and teams to sign off.
+    // While the organization is turbulent, we can do this.
+    // Once it's more settled, we can refactor the rest api code
+    // to leverage the OpenAPI urls rather than hardcoded urls.
+    const { hash, pathname } = window.location
+
+    // The `hash` will start with a `#` but all the keys in
+    // `overrideRedirects` do not. Hence, this slice.
+    const combined = pathname + hash
+    const overrideKey = combined
+      .replace(`/${router.locale}`, '')
+      .replace(`/${router.query.versionId || ''}`, '')
+    const redirectToName = overrideRedirects[overrideKey]
+    if (redirectToName) {
+      const newPathname = combined.replace(overrideKey, redirectToName)
+      router.replace(newPathname)
+    }
+  }, [])
+
+  return null
+}

components/page-header/RestRepoBanner.tsx

@@ -11,7 +11,7 @@ const restDisplayPages = [
   '/rest/reference/pages',
   '/rest/reference/releases',
   '/rest/reference/repos',
-  '/rest/reference/repository-metrics',
+  '/rest/reference/metrics',
   '/rest/reference/webhooks',
 ]
 const restRepoCategoryExceptionsTitles = {
@@ -21,7 +21,7 @@ const restRepoCategoryExceptionsTitles = {
   deployments: 'Deployments',
   pages: 'GitHub Pages',
   releases: 'Releases',
-  'repository-metrics': 'Repository metrics',
+  metrics: 'Metrics',
   webhooks: 'Webhooks',
 }
 

content/rest/reference/branches.md

@@ -12,19 +12,11 @@ topics:
 miniTocMaxHeadingLevel: 3
 ---
 
-## Branches
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'branches' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
 {% endfor %}
 
-## Merging
-
-The Repo Merging API supports merging branches in a repository. This accomplishes
-essentially the same thing as merging one branch into another in a local repository
-and then pushing to {% data variables.product.product_name %}. The benefit is that the merge is done on the server side and a local repository is not needed. This makes it more appropriate for automation and other tools where maintaining local repositories would be cumbersome and inefficient.
-
-The authenticated user will be the author of any merges done through this endpoint.
-
+## Protected branches
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'merging' %}{% include rest_operation %}{% endif %}
+  {% if operation.subcategory == 'branch-protection' %}{% include rest_operation %}{% endif %}
 {% endfor %}

content/rest/reference/collaborators.md

@@ -12,10 +12,8 @@ topics:
 miniTocMaxHeadingLevel: 3
 ---
 
-## Collaborators
-
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'collaborators' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
 {% endfor %}
 
 ## Invitations

content/rest/reference/commits.md

@@ -1,6 +1,6 @@
 ---
 title: Commits
-intro: 'The commits API allows you to retrieve information and commits, create commit comments, and create commit statuses.'
+intro: 'The commits API allows you to list, view, and compare commits in a repository. You can also interact with commit comments and commit statuses.'
 allowTitleToDifferFromFilename: true
 versions:
   fpt: '*'
@@ -12,12 +12,8 @@ topics:
 miniTocMaxHeadingLevel: 3
 ---
 
-## Commits
-
-The Repo Commits API supports listing, viewing, and comparing commits in a repository.
-
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'commits' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
 {% endfor %}
 
 ## Commit comments

content/rest/reference/deployments.md

@@ -12,18 +12,6 @@ topics:
 miniTocMaxHeadingLevel: 3
 ---
 
-## Deploy keys
-
-{% 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)."
-
-{% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'keys' %}{% include rest_operation %}{% endif %}
-{% endfor %}
-
-## Deployments
-
 Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a [`deployment` event](/developers/webhooks-and-events/webhook-events-and-payloads#deployment) that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).
 
 Deployment statuses allow external services to mark deployments with an `error`, `failure`, `pending`, `in_progress`, `queued`, or `success` state that systems listening to [`deployment_status` events](/developers/webhooks-and-events/webhook-events-and-payloads#deployment_status) can consume.
@@ -66,15 +54,30 @@ Keep in mind that GitHub is never actually accessing your servers. It's up to yo
 
 Note that the `repo_deployment` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to deployments and deployment statuses **without** granting access to repository code, while the {% ifversion not ghae %}`public_repo` and{% endif %}`repo` scopes grant permission to code as well.
 
-
 ### Inactive deployments
 
 When you set the state of a deployment to `success`, then all prior non-transient, non-production environment deployments in the same repository with the same environment name will become `inactive`. To avoid this, you can set `auto_inactive` to `false` when creating the deployment status.
 
 You can communicate that a transient environment no longer exists by setting its `state` to `inactive`.  Setting the `state` to `inactive` shows the deployment as `destroyed` in {% data variables.product.prodname_dotcom %} and removes access to it.
 
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'deployments' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
+{% endfor %}
+
+## Deployment statuses
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'statuses' %}{% include rest_operation %}{% endif %}
+{% endfor %}
+
+## Deploy keys
+
+{% 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)."
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'keys' %}{% include rest_operation %}{% endif %}
 {% endfor %}
 
 {% ifversion fpt or ghes > 3.1 or ghae or ghec %}

content/rest/reference/index.md

@@ -19,32 +19,32 @@ children:
   - /codes-of-conduct
   - /code-scanning
   - /codespaces
-  - /commits
   - /collaborators
+  - /commits
   - /dependabot
   - /deployments
   - /emojis
   - /enterprise-admin
   - /gists
   - /git
-  - /pages
   - /gitignore
   - /interactions
   - /issues
   - /licenses
   - /markdown
   - /meta
+  - /metrics
   - /migrations
   - /oauth-authorizations
   - /orgs
   - /packages
+  - /pages
   - /projects
   - /pulls
   - /rate-limit
   - /reactions
   - /releases
   - /repos
-  - /repository-metrics
   - /scim
   - /search
   - /secret-scanning

content/rest/reference/repository-metrics.md renamed to content/rest/reference/metrics.md

@@ -1,7 +1,9 @@
 ---
-title: Repository metrics
+title: Metrics
 intro: 'The repository metrics API allows you to retrieve community profile, statistics, and traffic for your repository.'
 allowTitleToDifferFromFilename: true
+redirect_from:
+  - /rest/reference/repository-metrics
 versions:
   fpt: '*'
   ghes: '*'
@@ -12,6 +14,10 @@ topics:
 miniTocMaxHeadingLevel: 3
 ---
 
+{% for operation in currentRestOperations %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
+{% endfor %}
+
 {% ifversion fpt or ghec %}
 ## Community
 

content/rest/reference/pages.md

@@ -28,5 +28,5 @@ In {% data variables.product.prodname_pages %} API endpoints that  return GitHub
    - `path`: The repository directory from which the site publishes. Will be either `/` or `/docs`.
 
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'pages' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
 {% endfor %}

content/rest/reference/releases.md

@@ -19,5 +19,11 @@ miniTocMaxHeadingLevel: 3
 {% endnote %}
 
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'releases' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
+{% endfor %}
+
+## Release assets 
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'assets' %}{% include rest_operation %}{% endif %}
 {% endfor %}

content/rest/reference/webhooks.md

@@ -19,18 +19,36 @@ If you would like to set up a single webhook to receive events from all of your
 In addition to the REST API, {% data variables.product.prodname_dotcom %} can also serve as a [PubSubHubbub](#pubsubhubbub) hub for repositories.
 
 {% for operation in currentRestOperations %}
-  {% if operation.subcategory == 'webhooks' %}{% include rest_operation %}{% endif %}
+  {% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
 {% endfor %}
 
-### Receiving Webhooks
+## Repository webhooks
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'repos' %}{% include rest_operation %}{% endif %}
+{% endfor %}
+
+## Repository webhook configuration
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'repo-config' %}{% include rest_operation %}{% endif %}
+{% endfor %}
+
+## Repository webhook deliveries
+
+{% for operation in currentRestOperations %}
+  {% if operation.subcategory == 'repo-deliveries' %}{% include rest_operation %}{% endif %}
+{% endfor %}
+
+## Receiving Webhooks
 
 In order for {% data variables.product.product_name %} to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.
 
-#### Webhook headers
+### Webhook headers
 
 {% data variables.product.product_name %} will send along several HTTP headers to differentiate between event types and payload identifiers. See [webhook headers](/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers) for details.
 
-### PubSubHubbub
+## PubSubHubbub
 
 GitHub can also serve as a [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub) hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL.
 Topic URLs for a GitHub repository's pushes are in this format:
@@ -39,21 +57,21 @@ Topic URLs for a GitHub repository's pushes are in this format:
 
 The event can be any available webhook event. For more information, see "[Webhook events and payloads](/developers/webhooks-and-events/webhook-events-and-payloads)."
 
-#### Response format
+### Response format
 
 The default format is what [existing post-receive hooks should expect](/post-receive-hooks/): A JSON body sent as the `payload` parameter in a POST.  You can also specify to receive the raw JSON body with either an `Accept` header, or a `.json` extension.
 
     Accept: application/json
     https://github.com/{owner}/{repo}/events/push.json
 
-#### Callback URLs
+### Callback URLs
 
 Callback URLs can use the `http://` protocol.
 
     # Send updates to postbin.org
     http://postbin.org/123
 
-#### Subscribing
+### Subscribing
 
 The GitHub PubSubHubbub endpoint is: `{% data variables.product.api_url_code %}/hub`. A successful request with curl looks like:
 
@@ -67,7 +85,7 @@ curl -u "user" -i \
 
 PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.
 
-##### Parameters
+#### Parameters
 
 Name | Type | Description
 -----|------|--------------

data/reusables/webhooks/webhooks-rest-api-links.md

@@ -1,5 +1,5 @@
 The webhook REST APIs enable you to manage repository, organization, and app webhooks.{% ifversion fpt or ghes > 3.2 or ghae or ghec %} You can use this API to list webhook deliveries for a webhook, or get and redeliver an individual delivery for a webhook, which can be integrated into an external app or service.{% endif %} You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:
 
-- [Repository Webhooks REST API](/rest/reference/repos#webhooks)
+- [Repository Webhooks REST API](/rest/reference/webhooks#repository-webhooks)
 - [Organization Webhooks REST API](/rest/reference/orgs#webhooks)
 - [{% data variables.product.prodname_github_app %} Webhooks REST API](/rest/reference/apps#webhooks)