Add basic auth to REST doc and examples (#50758)

Co-authored-by: Sarah Edwards <skedwards88@github.com>
Co-authored-by: Peter Bengtsson <peterbe@github.com>

data/ui.yml

@@ -182,6 +182,8 @@ rest_reference:
   installation_access_token_name: GitHub App installation access tokens
   fine_grained_access_token_name: Fine-grained personal access tokens
   no_fine_grained_access: This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
+  basic_auth_heading: Basic authentication for "{{ RESTOperationTitle }}"
+  basic_auth: You must use <a href="/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication">Basic Authentication</a> to use this endpoint. Use the application's <code>client_id</code> as the username and the <code>client_secret</code> as the password.
 webhooks:
   action_type_switch_error: There was an error switching webhook action types.
   action_type: Action type

src/fixtures/fixtures/data/ui.yml

@@ -182,6 +182,8 @@ rest_reference:
   installation_access_token_name: GitHub App installation access tokens
   fine_grained_access_token_name: Fine-grained personal access tokens
   no_fine_grained_access: This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
+  basic_auth_heading: Basic authentication for "{{ RESTOperationTitle }}"
+  basic_auth: You must use <a href="/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication">Basic Authentication</a> to use this endpoint. Use the application's <code>client_id</code> as the username and the <code>client_secret</code> as the password.
 webhooks:
   action_type_switch_error: There was an error switching webhook action types.
   action_type: Action type

src/github-apps/scripts/sync.js

@@ -185,6 +185,7 @@ export async function getProgAccessData(progAccessSource, isRest = false) {
         : operation.permission_sets || [],
       allowPermissionlessAccess: operation.allows_permissionless_access,
       allowsPublicRead: operation.allows_public_read,
+      basicAuth: operation.basic_auth,
     }
   }
 

src/rest/components/RestAuth.tsx

@@ -16,11 +16,10 @@ const FINE_GRAINED_TOKEN_PATH =
 type Props = {
   progAccess: ProgAccessT
   slug: string
-  heading: string
+  operationTitle: string
 }
 
-export function RestAuth({ progAccess, slug, heading }: Props) {
+export function RestAuth({ progAccess, slug, operationTitle }: Props) {
-  const router = useRouter()
   const { currentVersion } = useVersion()
   const { t } = useTranslation('rest_reference')
 
@@ -29,30 +28,48 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
   if (currentVersion === 'enterprise-server@3.9' || currentVersion === 'enterprise-server@3.8')
     return null
 
-  let basePath = `/${router.locale}`
-  if (currentVersion !== DEFAULT_VERSION) {
-    basePath += `/${currentVersion}`
-  }
-
   // There are some operations that have no progAccess access defined
   // For those operations, we shouldn't display this component
   if (!progAccess) return null
-  const { userToServerRest, serverToServer, fineGrainedPat } = progAccess
+  const { userToServerRest, serverToServer, fineGrainedPat, basicAuth = false } = progAccess
   const noFineGrainedAcccess = !(userToServerRest || serverToServer || fineGrainedPat)
 
-  // Pluralize the message if needed or customize it
+  const heading = basicAuth ? t('basic_auth_heading') : t('fine_grained_access')
-  // when no permissions are defined
+  const headingId = heading.replace('{{ RESTOperationTitle }}', operationTitle)
-  const numPermissionSets = progAccess.permissions.length
+  const authSlug = basicAuth
-  const permissionMsg =
+    ? `${slug}--basic-authentication`
-    numPermissionSets === 0
+    : `${slug}--fine-grained-access-tokens`
-      ? t('no_permission_sets')
+
-      : numPermissionSets > 1
+  return (
-        ? t('permission_sets') + ':'
+    <>
-        : t('permission_set') + ':'
+      <h3 className="mt-4 mb-3 pt-3 h4" id={authSlug}>
-  const publicAccessMsg =
+        <a href={`#${authSlug}`}>{headingId}</a>
-    numPermissionSets === 0
+      </h3>
-      ? t('allows_public_read_access_no_permissions')
+      {noFineGrainedAcccess ? (
-      : t('allows_public_read_access')
+        <NoFineGrainedAccess basicAuth={basicAuth} />
+      ) : (
+        <FineGrainedAccess progAccess={progAccess} />
+      )}
+    </>
+  )
+}
+
+function NoFineGrainedAccess({ basicAuth }: { basicAuth: boolean }) {
+  const { t } = useTranslation('rest_reference')
+
+  if (basicAuth) return <p dangerouslySetInnerHTML={{ __html: t('basic_auth') }}></p>
+  return <p>{t('no_fine_grained_access')}</p>
+}
+
+type FineGrainedProps = {
+  progAccess: ProgAccessT
+}
+
+function FineGrainedAccess({ progAccess }: FineGrainedProps) {
+  const router = useRouter()
+  const { currentVersion } = useVersion()
+  const { t } = useTranslation('rest_reference')
+
   // progAccess.permissions is an array of objects
   // For example: [ {'"Actions" repository permissions': 'read', '"Administration" organization permissions': 'write'}, {'"Secrets" organization permissions"': 'write'} ]
   // Each object represents a set of permissions containing one
@@ -77,7 +94,26 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
     )
   })
 
-  const fineGrainedData = (
+  let basePath = `/${router.locale}`
+  if (currentVersion !== DEFAULT_VERSION) {
+    basePath += `/${currentVersion}`
+  }
+
+  // Pluralize the message if needed or customize it
+  // when no permissions are defined
+  const numPermissionSets = progAccess.permissions.length
+  const permissionMsg =
+    numPermissionSets === 0
+      ? t('no_permission_sets')
+      : numPermissionSets > 1
+        ? t('permission_sets') + ':'
+        : t('permission_set') + ':'
+  const publicAccessMsg =
+    numPermissionSets === 0
+      ? t('allows_public_read_access_no_permissions')
+      : t('allows_public_read_access')
+
+  return (
     <>
       <p>{t('works_with_fine_grained_tokens')}:</p>
       <ul>
@@ -106,13 +142,4 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
       {progAccess.allowsPublicRead && <p>{publicAccessMsg}</p>}
     </>
   )
-
-  return (
-    <>
-      <h3 className="mt-4 mb-3 pt-3 h4" id={`${slug}--fine-grained-access-tokens`}>
-        <a href={`#${slug}--fine-grained-access-tokens`}>{heading}</a>
-      </h3>
-      {noFineGrainedAcccess ? <p>{t('no_fine_grained_access')}</p> : fineGrainedData}
-    </>
-  )
 }

src/rest/components/RestOperation.tsx

@@ -70,7 +70,7 @@ export function RestOperation({ operation }: Props) {
           <RestAuth
             progAccess={operation.progAccess}
             slug={titleSlug}
-            heading={t('fine_grained_access').replace('{{ RESTOperationTitle }}', operation.title)}
+            operationTitle={operation.title}
           />
 
           {hasParameters && (

src/rest/components/get-rest-code-samples.ts

@@ -93,6 +93,10 @@ export function getShellExample(
     acceptHeader = acceptHeader === `-H "Accept: application/vnd.github+json"` ? '' : acceptHeader
   }
 
+  if (operation?.progAccess?.basicAuth) {
+    authHeader = '-u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>"'
+  }
+
   const args = [
     operation.verb !== 'get' && `-X ${operation.verb.toUpperCase()}`,
     acceptHeader,
@@ -121,6 +125,9 @@ export function getGHExample(
   currentVersion: string,
   allVersions: Record<string, VersionItem>,
 ) {
+  // Basic authentication is not supported by GH CLI
+  if (operation?.progAccess?.basicAuth) return
+
   const defaultAcceptHeader = getAcceptHeader(codeSample)
   const hostname = operation.serverUrl !== 'https://api.github.com' ? '--hostname HOSTNAME' : ''
 
@@ -326,9 +333,12 @@ export function getJSExample(
   }
 
   const comment = `// Octokit.js\n// https://github.com/octokit/core.js#readme\n`
-  const require = `const octokit = new Octokit(${stringify({ auth: 'YOUR-TOKEN' }, null, 2)})\n\n`
+  const authOctokit = `const octokit = new Octokit(${stringify({ auth: 'YOUR-TOKEN' }, null, 2)})\n\n`
+  const oauthOctokit = `import { createOAuthAppAuth } from "@octokit/auth-oauth-app"\n\nconst octokit = new Octokit({\n  authStrategy: createOAuthAppAuth,\n  auth:{\n    clientType: 'oauth-app',\n    clientId: '<YOUR_CLIENT ID>',\n    clientSecret: '<YOUR_CLIENT SECRET>'\n  }\n})\n\n`
+  const isBasicAuth = operation?.progAccess?.basicAuth
+  const authString = isBasicAuth ? oauthOctokit : authOctokit
 
-  return `${comment}${require}await octokit.request('${operation.verb.toUpperCase()} ${
+  return `${comment}${authString}await octokit.request('${operation.verb.toUpperCase()} ${
     operation.requestPath
   }${queryParameters}', ${stringify(parameters, null, 2)})`
 }

src/rest/components/types.ts

@@ -21,6 +21,7 @@ export interface ProgAccessT {
   permissions: Array<Object>
   allowPermissionlessAccess?: boolean
   allowsPublicRead?: boolean
+  basicAuth?: boolean
 }
 
 export interface Parameter {

src/rest/data/fpt-2022-11-28/schema.json

@@ -84928,7 +84928,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -96146,7 +96147,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -96217,7 +96219,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -97227,7 +97230,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -98233,7 +98237,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghec-2022-11-28/schema.json

@@ -94538,7 +94538,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -105756,7 +105757,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -105827,7 +105829,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -106837,7 +106840,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -107843,7 +107847,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghes-3.10-2022-11-28/schema.json

@@ -93569,7 +93569,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -101792,7 +101793,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -101863,7 +101865,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102848,7 +102851,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -103829,7 +103833,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghes-3.11-2022-11-28/schema.json

@@ -93593,7 +93593,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -101816,7 +101817,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -101887,7 +101889,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102872,7 +102875,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -103853,7 +103857,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghes-3.12-2022-11-28/schema.json

@@ -93769,7 +93769,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102077,7 +102078,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102148,7 +102150,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -103150,7 +103153,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -104148,7 +104152,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghes-3.13-2022-11-28/schema.json

@@ -93861,7 +93861,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102209,7 +102210,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102280,7 +102282,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -103290,7 +103293,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -104296,7 +104300,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {

src/rest/data/ghes-3.9-2022-11-28/schema.json

@@ -92555,7 +92555,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -100774,7 +100775,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -100845,7 +100847,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -101830,7 +101833,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {
@@ -102811,7 +102815,8 @@
           "userToServerRest": false,
           "serverToServer": false,
           "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
         },
         "codeExamples": [
           {