github_api.saas.txt

                                  ┏━━━━━━━━━━━━━━━━┓
                                  ┃   GITHUB_API   ┃
                                  ┗━━━━━━━━━━━━━━━━┛

GITHUB API ==>                    #Version 2022-11-28

GITHUB MAIN|CLI|WEBHOOKS|APPS
 |ACTIONS ==>                     #See other GitHub docs

GITHUB ENTERPRISE ==>             #Not documented yet

SUMMARY ==>                       #General: version, user-agent, OpenAPI, ID|node_id
                                  #MIME: JSON, Markdown -> HTML, raw
                                  #Auth: API_PERMISSIONs, PAT, APP_JWT, IAT, UAT, Basic, anonymous
                                  #Interface: REST|GraphQL, Octokit client, plugins, mocks
                                  #API features: rate limiting, pagination, sort, caching, logging, retry, errors
                                  #Specific endpoints: contents

                                  ┌─────────────┐
                                  │   GENERAL   │
                                  └─────────────┘

https://api.github.com            #API root
https://uploads.github.com        #API root for POST RREPO/releases/ID/assets
https://github.com                #API root for /login, /settings

RREPO                             #/repos/USER/REPO
OORG                              #/orgs/ORG
UUSER                             #/users/USER

GET /                             #Return all API endpoints
GET /meta                         #Return information about: server IPs, domain names, SSH keys

X-GitHub-Api-Version:
 YYYY-MM-DD [C]                   #
GET /versions                     #Returns 'YYYY-MM-DD'_ARR

User-Agent: STR [C]               #Must be specified
KOPTS.userAgent
User-Agent:
 octokit-CALLER.js/X.Y.Z
 BROWSER_USER_AGENT [C]           #CALLER depends on library used: nothing, core, rest, action, request, graphql, auth-app, auth-oauth-app, auth-oath-device

                                  ┌──────────────────┐
                                  │   OPENAPI MAIN   │
                                  └──────────────────┘

OPENAPI ==>                       #3.0

@octokit/openapi                  #Version 13.2.0
                                  #Updated very often, so not latest version documented here
schemas['api.github.com']         #OpenAPI OBJ
schemas['api.github.com.deref']   #Same but inlines all $ref

OPERATION.operationId             #'SCOPE/METHOD' e.g.:
                                  #  - 'meta/root': GET /
                                  #  - 'apps/create-from-manifest': GET /app-manifests/{code}/conversions
                                  #Not documented in REST API, i.e. must check OpenAPI document instead
OPERATION['x-github'].category    #STR, e.g. 'branches'. Main category, like 'SCOPE' but meant for documentation
OPERATION['x-github'].subcategory #STR, e.g. 'branch-protection'. Subcategory
OPERATION['x-github']
 .enabledForGitHubApps            #BOOL. Whether can be used with GitHub app UAT
OPERATION['x-github']
 .triggersNotifications           #BOOL
OPERATION['x-github']             #BOOL. Whether only for GitHub Cloud users.
 .githubCloudOnly                 #Only true for Actions self-hosted runners.
OPERATION['x-github']
 .requestBodyParameterName        #'VAR'. For endpoints with both query variables and request body, name of the request body
OPERATION['x-github']
 .deprecatedDate                  #'DATE'
OPERATION['x-github'].removalDate #'DATE'
OPERATION['x-octokit'].changes    #OPENAPI_CHANGE_ARR. Breaking changes
OPENAPI_CHANGE.type               #'PARAMETER|OPERATION'
OPENAPI_CHANGE.date               #'YYYY-MM-DD'
OPENAPI_PARAM_CHANGE.parameter    #'NEW_VAR'
OPENAPI_PARAM_CHANGE.before.name  #'OLD_VAR'
OPENAPI_OP_CHANGE
 .before.operationId              #'OLD_SCOPE/OLD_METHOD'

@octokit/types                    #TypeScript types generated from OpenAPI
                                  #Not documented yet

                                  ┌─────────────────────┐
                                  │   GRAPHQL OPENAPI   │
                                  └─────────────────────┘

github-openapi-graphql-query      #Version 4.5.0
                                  #GitHub API OpenAPI, as GraphQL
                                  #Uses @octokit/openapi GitHub releases, fetched with HTTP calls (memoized)

GOGQ('QUERY'[, OBJ])->>RES_OBJ    #Perform GraphQL QUERY (using graphql.js), with OBJ as variables
ENVVAR GITHUB_TOKEN               #Can be set (for lower rate limiting)

query.releases                    #RELEASE_ARR
query.lastRelease                 #RELEASE
RELEASE                           #@octokit/openapi GitHub releases
query.endpoint[s](version:'X.Y.Z')
RELEASE.version                   #'X.Y.Z'
RELEASE.createdAt                 #'DATE'

query.endpoints                   #ENDPOINT_ARR
query.endpoints(filter: FILTER)   #
query.endpoints(limit: INT)       #

query.endpoint
 (route: 'METHOD /PATH')          #ENDPOINT

ENDPOINT.scope                    #'SCOPE' (from OPERATION.operationId)
ENDPOINT.id                       #'METHOD' (from OPERATION.operationId)
ENDPOINT.name                     #STR. Short description (from OPERATION.summary)
ENDPOINT.description              #'MARKDOWN'. Long description (from OPERATION.description)
ENDPOINT.method                   #'HTTP_METHOD' (from PATHDEF.HTTP_METHOD)
ENDPOINT.url                      #'{origin}/PATH[{?VAR,...}]', including any '{VAR}' (from PATHS./PATH)
                                  #VAR are query PARAMs, if POST|PUT|PATCH|DELETE method
                                  #`origin` is a `path` PARAM
                                  #  - description|default from SPEC|OPERATION.servers
                                  #  - 'https://api.github.com' for all, except 'https://uploads.github.com'
ENDPOINT.documentationUrl         #'URL' (from OPERATION.externalDocs.url)
ENDPOINT|FILTER.isDeprecated      #BOOL (from OPERATION.deprecated)
ENDPOINT.deprecationDate          #STR (from OPERATION['x-github'].deprecatedDate)
ENDPOINT.removalDate              #STR (from OPERATION['x-github'].removalDate)
ENDPOINT|FILTER.isEnabledForApps  #BOOL (from OPERATION['x-github'].isEnabledForApps)
ENDPOINT|FILTER.isGitHubCloudOnly #BOOL (from OPERATION['x-github'].isGitHubCloudOnly)
ENDPOINT.triggersNotification     #BOOL (from OPERATION['x-github'].triggersNotification)
                                  #Whether triggers email notification

ENDPOINT.parameters               #PARAMETER_ARR (from PARAMs where PARAM.in 'path|query|body')
PARAMETER.name                    #'PARAM_VAR', from either:
                                  #  - PARAM.name
                                  #  - OPERATION['x-github'].requestBodyParameterName
                                  #  - REQ_BODY SCHEMA.properties.VARR
                                  #  - REQ_BODY SCHEMA.additionalProperties (as '*')
PARAMETER.in                      #'PATH|QUERY|BODY' (from PARAM.in)
PARAMETER.description             #STR (from PARAM.description or REQ_BODY SCHEMA.description)
PARAMETER.required                #BOOL (from PARAM.required or REQ_BODY SCHEMA.required)
PARAMETER.allowNull               #BOOL (from PARAM.nullable or REQ_BODY SCHEMA.nullable)
PARAMETER.validation              #STR|null (from PARAM.pattern or REQ_BODY SCHEMA.pattern)
PARAMETER.type                    #STR (from PARAM.schema.type or REQ_BODY SCHEMA.type)
                                  #If REQ_BODY and SCHEMA.type 'array', uses SCHEMA.items.type and appends '[]'
PARAMETER.enum                    #STR_ARR (from PARAM.schema.enum or REQ_BODY SCHEMA.enum)
PARAMETER.deprecated              #BOOL (from OPERATION['x-octokit'].changes)
PARAMETER.alias                   #STR (from OPERATION['x-octokit'].changes)
PARAMETER.mapToData               #BOOL|null. true with REQ_BODY
PARAMETER.default                 #STR (only with `origin` PARAM)

ENDPOINT.headers                  #HEADER_ARR|null (from PARAMs where PARAM.in 'header')
HEADER.name                       #'PARAM_VAR' (from PARAM.name)
HEADER.description                #STR (from PARAM.description)
HEADER.required                   #BOOL (from PARAM.required)
HEADER.value                      #STR|null (from PARAM.schema.enum[0] or PARAM.schema.default)

ENDPOINT.responses(code: CODE_*)  #RESPONSE_ARR (from RESPONSES)
                                  #CODE_* can be CODE_2xx|4xx or specific ones like CODE_205
RESPONSE.code                     #INT (from RESPONSES.HTTP_STATUS_CODE)
RESPONSE.description              #STR (from RESP.description)
RESPONSE.mediaType                #'MIME_RANGE' (from RESP.content.MIME_RANGE)
RESPONSE.schema                   #'OBJ_JSON' (from CONTENT.schema)

RESPONSE.examples                 #EXAMPLE_ARR (from CONTENT.example[s])
EXAMPLE.name                      #STR (from CONTENT.examples.MIME)
EXAMPLE.data                      #'JSON' (from CONTENT.examples or EXAMPLE.value)

ENDPOINT.changes(type:CHANGE.type)#CHANGE_ARR (from OPERATION['x-octokit'].changes)
CHANGE.type                       #OPERATION|PARAMETER
CHANGE.date                       #'DATE'
CHANGE.parameter                  #'VAR'
CHANGE.note                       #STR

CHANGE.before|after               #OP_CHANGE|PARAM_CHANGE
OP_CHANGE.operationId             #'SCOPE/METHOD'
OP_CHANGE|PARAM_CHANGE.description#STR
PARAM_CHANGE.*                    #Like PARAMETER.* except no deprecated|alias|required

ENDPOINT.renamed                  #RENAME (simplification of ENDPOINT.changes)
RENAME.before|after.scope         #'SCOPE'
RENAME.before|after.id            #'METHOD'
RENAME.date                       #'DATE'
RENAME.note                       #STR

query.endpoints
 (ignoreChangesBefore: 'DATE')    #Ignore old|deprecated endpoints|params before 'DATE'

RENAME.before|after(format:FORMAT)
 .id|scope(format: FORMAT)
ENDPOINT.id|scope(format: FORMAT) #FORMAT can be KEBABCASE (def) or CAMELCASE

                                  ┌────────┐
                                  │   ID   │
                                  └────────┘

X-Github-Request-Id: STR [S]      #

RESOURCE.id                       #NUM. TYPE-specific resource ID
RESOURCE.node_id                  #'NODE_ID', i.e. 'API_VERSION:TypeID' base64'd. TYPE-agnostic resource ID

GRAPHQL_RESOURCE.id               #'NODE_ID'
query.node(id: 'NODE_ID')         #RESOURCE_OBJ
query.nodes(id: 'NODE_ID'_ARR)    #RESOURCE_OBJ_ARR
query.resource(url: 'URL')        #RESOURCE_OBJ

                                  ┌──────────┐
                                  │   MIME   │
                                  └──────────┘

Accept:
 application/vnd.github[+json] [C]#
Accept: application/json [C]      #

Accept: application/              #When returning comments with Markdown, FORMAT can be:
 vnd.github.FORMAT+json [C]       #  - 'raw': as is, under `body`
                                  #  - 'text': as text, under `body_text`
                                  #  - 'html', under `body_html`
                                  #  - 'full', all

Accept:                           #When returning REPO files, FORMAT can be:
 application/vnd.github.FORMAT [C]#  - 'raw': as is
                                  #     - only one supported if contents >1MB
                                  #  - 'html': as HTML, if Markdown
                                  #  - 'object': as an API RES

POST /markdown                    #Render Markdown as HTML
REQ.text                          #'MARKDOWN'
REQ.mode                          #'markdown' (def) or 'gfm'
REQ.context                       #'USER/REPO' to render #NUM, only with REQ.mode 'gfm'

POST /markdown/raw                #Same but whole REQ is 'MARKDOWN'

Accept:
 application/vnd.github.raw [C]   #When returning Git blob, return as is, instead of as { content: 'BASE64' }

                                  ┌──────────┐
                                  │   AUTH   │
                                  └──────────┘

Authorization: Bearer TOKEN [C]   #Can be: PAT or (see GitHub apps) APP_JWT, IAT, UAT

PAT                               #"Personal Access Token". Generated from the UI for a given user
                                  #Can restrict PERMISSIONS and set expiration

GITHUB ACTIONS ==>                #Should use ENVVAR GITHUB_TOKEN

                                  ┌─────────────────┐
                                  │   PERMISSIONS   │
                                  └─────────────────┘

API_PERMISSION                    #Scopes a PAT's privileges

PERMISSION_LEVEL                  #'read', 'write' or 'admin'

X-Accepted-GitHub-Permissions:
 API_PERMISSION=
 PERMISSION_LEVEL,... [S]         #Hint about permissions required for a given endpoint

ORG PERMISSIONS ==>               #
administration                    #
blocking_users                    #
events                            #
members                           #
organization_codespaces_secrets   #
organization_codespaces_settings  #
organization_codespaces           #
organization_dependabot_secrets   #
personal_access_token_requests    #
personal_access_tokens            #
projects                          #
secrets                           #
self_hosted_runners               #
team_discussions                  #
variables                         #
webhooks                          #

REPO PERMISSIONS ==>              #
actions                           #
administration                    #
checks                            #
code_scanning_alerts              #
codespaces_lifecycle_admin        #
codespaces_metadata               #
codespaces_secrets                #
codespaces                        #
commit_statuses                   #
contents                          #
dependabot_alerts                 #
dependabot_secrets                #
deployments                       #
environments                      #
issues                            #
metadata                          #
pages                             #
projects                          #
pull_requests                     #
repository_security_advisories    #
secret_scanning_alerts            #
secrets                           #
variables                         #
webhooks                          #
workflows                         #

USER PERMISSIONS ==>              #
block_another_user                #
codespaces_user_secrets           #
email_addresses                   #
followers                         #
gpg_keys                          #
gists                             #
git_ssh_keys                      #
interaction_limits                #
notifications                     #
plan                              #
profile                           #
ssh_signing_keys                  #
starring                          #
watching                          #

                                  ┌───────────────────┐
                                  │   RATE LIMITING   │
                                  └───────────────────┘

GET /rate_limit                   #
XRATE_LIMIT.rate
XRATE_LIMIT.resources.core        #XLIMITS. Default rate limits
XRATE_LIMIT.resources.search      #XLIMITS. Rate limits for non-code searches
XRATE_LIMIT.resources.code_search #XLIMITS. Rate limits for code searches
XRATE_LIMIT.resources.graphql     #XLIMITS. Rate limits for GraphQL
XRATE_LIMIT.resources
 .integration_manifest            #XLIMITS. Rate limits for creating apps (POST /app-manifests/CODE/conversions)
XRATE_LIMIT.resources
 .dependency_snapshots            #XLIMITS. Rate limits for creating dependency graph snapshots
XRATE_LIMIT.resources
 .code_scanning_upload            #XLIMITS. Rate limits for uploading SARIF results for code scanning
XRATE_LIMIT.resources.
 .actions_runner_registration     #XLIMITS. Rate limits for registering self-hosted GitHub actions runners

SECONDARY RATE LIMIT ==>          #Endpoint-specific rate limits
Retry-After: NUM [S]              #

XLIMITS.limit
X-RateLimit-Limit: NUM [S]        #Total
XLIMITS.used
X-RateLimit-Used: NUM [S]         #Used
XLIMITS.remaining
X-RateLimit-Remaining: NUM [S]    #Left
XLIMITS.reset
X-RateLimit-Reset: DATE_NUM [S]   #When `used` becomes 0

GRAPHQL ==>                       #Based on the number of individual RESOURCEs returned, including nested ones
query.rateLimit
 .limit|used|remaning|resetAt     #Like X-RateLimit-* [S]
query.rateLimit.cost              #Cost of current query
query.rateLimit.nodeCount         #Max amount of RESOURCEs in current query

                                  ┌──────────────┐
                                  │   THROTTLE   │
                                  └──────────────┘

@octokit/plugin-throttling        #9.6.0
                                  #Node/Deno/browsers
throttling                        #PLUGIN
                                  #Uses X-RateLimit-* [S] and Retry-After [S]

KOPTS.throttle.onRateLimit        #Required. Fired when hitting rate limit.
 (FUNC(NUM, KOPTS, OCORE, NUM2)   #If returning false, fails the request.
 ->BOOL)                          #Otherwise, retry it after NUM seconds.
                                  #NUM2 is number of times it's been retried through onRateLimit()
                                  #  - should avoid returning true unless NUM2 is 0
KOPTS.throttle
 .onSecondaryRateLimit(...)       #Required. Same but for secondary rate limit

KOPTS.throttle.enabled            #BOOL (def: true)
KOPTS.throttle
 .fallbackSecondaryRateRetryAfter #NUM (in sec, def: 1m). Fallback when Retry-After [S] not set
KOPTS.throttle.retryAfterBaseValue#NUM. Multiply amounf of time to wait by NUM/1000
KOPTS.throttle.timeout            #NUM (def: 2m). Stops retrying after NUMms

KOPTS.throttle.connection         #Allows "clustering", i.e. sharing rate limits between multiple clients, through Redis.
                                  #Not documented yet
KOPTS.throttle.id                 #'ID' (def: 'no-id'), to group clustering clients
KOPTS.throttle.Bottleneck         #Custom options using underlying Bottleneck library (not documented yet)

                                  ┌─────────────────────┐
                                  │   REST PAGINATION   │
                                  └─────────────────────┘

Link: <URL?PARAM=NUM>;
 rel="first|prev|next|last"
 ,... [S]                         #Always defined on collections
?page=NUM [C]
?since=DATE [C]
?before|after=CURSOR [C]          #Which request parameter to use depends on endpoint
?per_page=NUM [C]                 #Def: 30, max: 100
RES.total_count                   #NUM, on all paginated endpoints
RES.incomplete_results            #BOOL, only one some endpoints
RES.RESOURCEs                     #OBJ_ARR

@octokit/plugin-paginate-rest     #Version 11.6.0
                                  #Node/Deno/browsers
paginateRest                      #PLUGIN

OCORE.paginate(...)->>RES         #Forwards to OREQUEST(...), but repeats calls using Link: <...>: rel="next" [S]
OCORE.paginate
 (OCORE.rest.SCOPE.METHOD, ...)
 ->>RES                           #Same with OCORE.rest.SCOPE.METHOD(...)
composePaginateRest(OCORE, ...)   #Same as OCORE.paginate(...), but does not require PLUGIN to have added to OCORE

OCORE.paginate.iterator(...)
 ->OBJ_ASYNC_ITERABLE
composePaginateRest.iterator(...)
 ->OBJ_ASYNC_ITERABLE             #Same but iterates through ASYNC_ITERABLE instead of buffering all

OCORE.paginate
 (..., FUNC(OBJ)->OBJ)->>RES      #Map each paginated OBJ

paginatingEndpoints               #'HTTP_METHOD /PATH'_ARR with all paginated endpoints
isPaginatingEndpoint
 ('HTTP_METHOD /PATH')->BOOL      #Can be used as type guard in TypeScript

                                  ┌────────────────────────┐
                                  │   GRAPHQL PAGINATION   │
                                  └────────────────────────┘

query.RESOURCEs(first|last: INT)  #
query.RESOURCEs.totalCount        #INT
query.RESOURCEs.pageInfo
 .hasPreviousPage|hasNextPage     #BOOL

query.RESOURCEs
 (before|after: 'CURSOR')         #
query.RESOURCEs.edges[*].cursor   #'CURSOR'
query.RESOURCEs.pageInfo
 .startCursor|endCursor           #'CURSOR'

query.RESOURCEs
 (clientMutationId: STR)
query.RESOURCEs.clientMutationId  #STR used internally by Relay

@octokit/plugin-paginate-graphql  #Version 5.2.4
                                  #Node/Deno/browsers
paginateGraphQL                   #PLUGIN

OCORE.graphql.paginate(...)       #Forwards to OGRAPHQL(...) but repeats using:
                                  #  - response:
                                  #     - either:
                                  #        - forward: pageInfo.hasNextPage|endCursor
                                  #        - backward: pageInfo.hasPreviousPage|startCursor
                                  #     - must be requested in 'QUERY'
                                  #  - request:
                                  #     - (after: $cursor)
                                  #     - must use variable $cursor
                                  #Does not work with SUBRESOURCEs
OCORE.graphql.paginate
 .iterator(...)
 ->OBJ_ASYNC_ITERABLE             #Same but iterates through ASYNC_ITERABLE instead of buffering all

                                  ┌─────────────┐
                                  │   SORTING   │
                                  └─────────────┘

?sort=PROP                        #
?direction=asc|desc               #

query.RESOURCE(orderBy: OBJ)      #
OBJ.field                         #PROP (uppercase)
OBJ.direction                     #ASC|DESC

                                  ┌─────────────┐
                                  │   CACHING   │
                                  └─────────────┘

E-Tag: STR [S]
Last-Modified: STR [S]
If-None-Match: STR [C]
If-Modified-Since: STR [C]        #Available on some endpoints

                                  ┌───────────────┐
                                  │   REST MAIN   │
                                  └───────────────┘

REST ==>                          #RESTful API
                                  #CRUD with POST|PATCH|GET|DELETE
                                  #All return a RES except DELETE

/RESOURCE[/ID]                    #Top-level
/RESOURCE/ID/SUBRESOURCE[/ID2]    #Nested

X*                                #API request|response body
X*_U                              #For fields that can be specified on create|update
X*_C                              #For fields that can be specified on create but not update
X*_F                              #For fields that are only returned when a single resource is retrieved, not a list

UARR                              #ARR which can be updated with fields:
                                  #  - PROP: replace whole ARR
                                  #  - add|remove_PROP

                                  ┌─────────────────┐
                                  │   REST CLIENT   │
                                  └─────────────────┘

@octokit                          #Version 13.5.0
 /plugin-rest-endpoint-methods    #Node/Deno/browsers

restEndpointsMethods              #PLUGIN
legacyRestEndpointsMethods        #PLUGIN. Same except also defines OCORE.* = OCORE.rest.*

OCORE.rest.SCOPE.METHOD           #Forwards to OREQUEST('HTTP_METHOD /PATH'[, REQ_OPTS])->>RES
 ([REQ_OPTS])->>RES               #SCOPE.METHOD: from OpenAPI `operationId`
                                  #Typed using @octokit/types
                                  #Allows REQ_OPTS.NAME when OPERATION['x-github'].requestBodyParameterName 'NAME' defined
                                  #Deprecated endpoints|parameter names are changed to new name, then log a warning
                                  #Sets KOPTS.baseUrl with 'https://uploads.github.com'
                                  #Sets Content-Type: text/plain [C] with POST /markdown

                                  ┌──────────────────┐
                                  │   GRAPHQL MAIN   │
                                  └──────────────────┘

POST /graphql                     #GraphQL endpoint
                                  #Using REQ: query 'OBJ_JSON', variables 'OBJ_JSON'
                                  #Unlike REST:
                                  #  - can select and populate fields
                                  #  - lacks some endpoints

GRAPHIQL ==>                      #Available online

query.RESOURCEs                   #OBJ_ARR
                                  #Similar to REST /RESOURCE
query.RESOURCEs.nodes[*]
query.RESOURCEs.edges[*].node     #RESOURCE_OBJ

query.RESOURCE                    #OBJ
                                  #Similar to REST /RESOURCE/ID

query.RESOURCE.SUBRESOURCE[s]     #Populates
                                  #Similar to REST /RESOURCE/ID/SUBRESOURCE[/ID2]
                                  #Can use pagination, filtering, sorting
query.RESOURCE { ... on OBJ_TYPE }#Alternative, where RESOURCE is an UNION of all SUBRESOURCEs instead

query.viewer                      #Like GET /user (current USER)
query.user(login: 'USER')         #Like GET /user/USER
query.organization(login: 'ORG')  #Like GET /orgs/ORG
query.repository
 (owner: 'USER', name: 'REPO')    #Like GET /repos/USER/REPO

query.RESOURCE(ARG: VAL,...)      #Like REST query variables
mutation.RESOURCE(input:INPUT_OBJ)#Like REST request body
mutation.RESOURCE { ... }         #Like REST response body

CUSTOM SCALAR TYPES ==>           #
BigInt                            #BIGINT
Base64String                      #BASE64
URI                               #URI
Date                              #YYYYMMDD
DateTime                          #YYYYMMDDTHH:MM:SSZ
PreciseDateTime                   #YYYYMMDDTHH:MM:SS.SSSZ
GitTimestamp                      #Like DateTime but not UTC
GitRefname                        #refs/...
GitObjectId                       #Git OBJECT_ID
GitSSHRemote                      #SSH connection string
HTML                              #HTML
X509Certificate                   #PEM

OCORE.graphql                     #OGRAPHQL

@octokit/graphql                  #Version 8.2.1
                                  #Node/Deno/browsers
graphql                           #OGRAPHQL
OGRAPHQL(REQ_OPTS|'QUERY')->>GRES #POST /graphql using OREQUEST(REQ_OPTS)
REQ_OPTS.query                    #'QUERY', passed as REQ.query
REQ_OPTS.VAR                      #GraphQL variables, passed as REQ.variables
RAWRES                            #GraphQL raw response
GRES.*                            #RAWRES.data.*

OGRAPHQL.defaults(REQ_OPTS)
 ->OGRAPHQL                       #
OGRAPHQL.endpoint                 #ENDPOINT
withCustomRequest(OREQUEST)
 ->OGRAPHQL                       #

@octokit/graphql-schema           #Version 14.39.0
                                  #Updated very often, so not latest version documented here
validate('QUERY')                 #Forwards to graphql.js validate(...)
 ->GRAPHQLERROR_ARR|null          #Builds SCHEMA using schema.json + graphql.js buildClientSchema()
                                  #Builds DOCUMENT_NODE using graphql-tag (see its doc)
schema.idl                        #'GRAPHQL' of all TYPE definitions
schema.json.__schema              #GraphQL SCHEMA

                                  ┌────────────┐
                                  │   ERRORS   │
                                  └────────────┘

ERROR_RES.message                 #'MESSAGE'

ERROR_RES.errors                  #RESERR_ARR|undefined
RESERR.code                       #'ERROR_CODE'
RESERR.documentation_url          #'URL'
RESERR.resource                   #'RESOURCE' (e.g. 'Issue')
RESERR.field                      #'PROP'
RESERR.missing                    #'RESOURCE', when missing
RESERR.missing_field              #'PROP', when missing
RESERR.already_exists             #'RESOURCE', when already exists
RESERR.invalid                    #'PROP', when invalid format
RESERR.unprocessable              #'PROP', when invalid format

@octokit/octokit
RequestError                      #Forward to @octokit/request-error

@octokit/request-error            #6.1.7
                                  #Node/browser/Deno
ERROR.name                        #'HttpError'
ERROR.status                      #NUM
ERROR.request                     #NREQ_OPTS
ERROR.response                    #RES

GraphqlResponseError              #Thrown if RAWRES.errors
GERROR.name                       #'GraphqlResponseError'
GERROR.message                    #'Request failed due to following response errors:'
                                  #followed by bullet point list of RAWRES.errors[*].message
GERROR.errors                     #RAWRES.errors
GERROR.data                       #RAWRES.data

                                  ┌───────────┐
                                  │   RETRY   │
                                  └───────────┘

@octokit/plugin-retry             #Version 7.2.0
                                  #Node/Deno/browsers
retry                             #PLUGIN
                                  #Wraps OCORE.request(...) to retry on 5** and some 4**
                                  #Uses `bottleneck` (old unsupported library) under the hood

KOPTS.retry.enabled               #BOOL (def: true)
KOPTS.retry|request.retries
REQ_OPTS.request.retries          #NUM (def: 3)
REQ_OPTS.request.retryAfter       #NUM (in ms), constant delay
KOPTS.retry.retryAfterBaseValue   #NUM (in ms, def: 1000), initial delay
KOPTS.retry.doNotRetry            #HTTP_CODE_NUM_ARR (def: [400, 401, 403, 404, 410, 422])

ERROR.request.request.retryCount  #NUM

                                  ┌────────────┐
                                  │   CLIENT   │
                                  └────────────┘

@octokit/octokit                  #Version 4.1.2
                                  #Node/Deno/browsers (like @octokit/core)
Octokit                           #Forward to @octokit/core Octokit, but with some additional PLUGINs

@octokit/rest                     #Version 21.1.2
                                  #Node/Deno/browsers (like @octokit/core)
Octokit                           #Forwards to @octokit/core Octokit, but with some additional PLUGINs

@octokit/core                     #Version 6.1.4
                                  #Node
                                  #Deno, except Node middleware
                                  #Browsers too, but secrets should not be exposed to client code
new Octokit([KOPTS])              #OCORE
Octokit.defaults(KOPTS[(KOPTS2)])
 ->Octokit                        #

                                  ┌───────────────┐
                                  │   HTTP MAIN   │
                                  └───────────────┘

OCORE.request                     #OREQUEST
KOPTS.baseUrl                     #REQ_OPTS.baseUrl
KOPTS.request                     #REQ_OPTS.request

@octokit/request                  #Version 9.2.2
                                  #Node/Deno/browsers

OREQUEST                          #Make an HTTP request to GitHub API
 ('METHOD /PATH'[, REQ_OPTS])     #Uses @octokit/endpoint, with same OPTS, plus some additional OPTS.request.*
 ->>RES                           #Automatically parses|serializes request|response body
                                  #Throws either AbortError or RequestError

REQ_OPTS.request.signal           #ABORT_SIGNAL
REQ_OPTS.request.fetch            #FUNC (def: globalThis.fetch)
REQ_OPTS.request.redirect         #fetch() OPTS.redirect

RES.status                        #NUM
RES.url                           #'URL'
RES.headers                       #OBJ
RES.data                          #VAL
REQ_OPTS.request                  #BOOL. If true (def), RES.data uses fetch json|text|arrayBuffer() method according to Content-Type [S]
 .parseSuccessResponseBody        #Otherwise, keep fetch RES as is

OREQUEST.defaults(REQ_OPTS)
 ->REQUEST                        #Merge to default REQ_OPTS
OREQUEST.endpoint                 #ENDPOINT (from @octokit/endpoint)

                                  ┌──────────────────┐
                                  │   HTTP OPTIONS   │
                                  └──────────────────┘

@octokit/endpoint                 #Version 10.1.3
                                  #Node/Deno/browsers
ENDPOINT
 (['METHOD /PATH'][, REQ_OPTS])
 ->NREQ_OPTS                      #Normalize REQ_OPTS into NREQ_OPTS
defaults(OBJ)->ENDPOINT           #Merge to defaults values

REQ_OPTS.route                    #'METHOD /PATH'
REQ_OPTS.method                   #'METHOD' (def: 'GET')
REQ_OPTS.url                      #'/PATH' or absolute 'URL'. Can include :VAR
REQ_OPTS.baseUrl                  #Base 'URL' of REQ_OPTS.url, if absolute
                                  #Def: 'https://api.github.com'
REQ_OPTS.headers                  #OBJ. Def:
                                  #  Content-Type: application/json; charset=utf-8 [C]
                                  #  Accept: application/vnd.github.v3+json [C]
REQ_OPTS.mediaType.format         #'MIME' (def: '') like 'raw', 'diff' or 'text+json'
REQ_OPTS.data                     #VAL. Request body
REQ_OPTS.VAR                      #Either:
                                  #  - URL parameter
                                  #  - query variables (if GET|HEAD)
                                  #  - request body
REQ_OPTS.request                  #OBJ kept as is

NREQ_OPTS.method                  #'METHOD'
NREQ_OPTS.url                     #REQ_OPTS.url, after REQ_OPTS.baseUrl resolution, and templating with REQ_OPTS.VAR
NREQ_OPTS.headers                 #OBJ
NREQ_OPTS.body                    #VAL
NREQ_OPTS.request                 #

                                  ┌──────────┐
                                  │   AUTH   │
                                  └──────────┘

AUTHENTICATION ==>                #See GitHub apps docs for more info
                                  #Steps:
                                  #  - new Octokit() calls FUNC(**OPTS)->*APP once: to initialize auth
                                  #  - any request calls FUNC(*OPTS)->>*_INFO: use it in auth
                                  #  - later requests used value cached by *APP

KCORE.auth                        #BAPP|AAPP|PAPP|DAPP|UAPP|TAPP|ZAPP|CAPP|IAPP
                                  #I.e. FUNC(*OPTS)->>*_INFO

KOPTS.authStrategy                #createProbotAuth, createAppAuth, createOAuthAppAuth, createOAuthDeviceAuth, createOAuthUserAuth,
                                  #createTokenAuth, createUnauthenticatedAuth, createCallbackAuth or createActionAuth
                                  #I.e. FUNC(**OPTS)->*APP
                                  #Def:
                                  #  - if KOPTS.auth 'TOKEN': authToken()
                                  #  - otherwise: authUauthenticated()

KOPTS.auth                        #BBOOPTS|AAOPTS|PPOPTS|DDOPTS|UUOPTS|'TOKEN'|ZZOPTS|CCOPTS
                                  #I.e. OPTS passed to KOPTS.authStrategy
                                  #Can only be 'TOKEN' if KOPTS.authStrategy undefined

REQ_OPTS.request.hook             #Middleware FUNC(OREQUEST, NREQ_OPTS)->OREQUEST
                                  #Meant to be used with BAPP|AAPP|PAPP|DAPP|UAPP|TAPP|ZAPP|CAPP|IAPP.hook
                                  #  - automatically set according to KOPTS.authStrategy

                                  ┌─────────────┐
                                  │   LOGGING   │
                                  └─────────────┘

OCORE|KOPTS.log                   #LOGS_OBJ
REQ_OPTS.request.log              #Def: console, but debug|info is noop
                                  #Only used to log deprecated endpoints

@octokit/plugin-request-log       #Version 5.3.1
                                  #Node/Deno/browsers
requestLog                        #PLUGIN
                                  #Calls LOGS_OBJ.info('METHOD /PATH - HTTP_STATUS with id REQ_ID in DURATION') after each call

                                  ┌─────────────┐
                                  │   PLUGINS   │
                                  └─────────────┘

OCORE.hook.before
 ('request', FUNC(KOPTS)[->>])    #Before HTTP request
OCORE.hook.after
 ('request',FUNC(RES, KOPTS)[->>])#After HTTP request success
OCORE.hook.error('request',
 FUNC(ERROR, KOPTS)[->>])         #After HTTP request failure
OCORE.hook.wrap('request',        #Before|after HTTP request
 FUNC(OREQUEST, KOPTS)->>RES)     #Should forward to OREQUEST(KOPTS)->>RES

Octokit.plugin(PLUGIN,...)        #Add a PLUGIN
 ->Octokit                        #PLUGIN is FUNC(OCORE, KOPTS)->OBJ, which merges OBJ.* to OCORE.*
KOPTS.*                           #Used to pass PLUGIN options
                                  #Should usually namespace with PLUGIN name

DEFAULT PLUGINS ==>               #  - paginate-rest: @octokit/octokit, @octokit/action, @actions/github, @octokit/rest
                                  #  - paginate-graphql: @octokit/octokit
                                  #  - rest-endpoint-methods:
                                  #     - not legacy: @octokit/octokit, @actions/github
                                  #     - legacy: @octokit/action, @octokit/rest
                                  #  - retry, throttling: @octokit/octokit
                                  #  - request-log: @octokit/rest

                                  ┌───────────┐
                                  │   MOCKS   │
                                  └───────────┘

@octokit/fixtures                 #Version 23.1.1
nock                              #Forwards to NOCK

@octokit/fixtures-server          #HTTP server delivering @octokit/fixtures
                                  #Not documented yet

get('api.github.com/FIXTURE')     #FIXTURE_ARR must be passed to NOCK.define()
 ->FIXTURE_ARR                    #Normalized (hardcoded IDs, DATEs, NUMs, TOKENs, etc.)

mock('api.github.com/FIXTURE'     #Calls NOCK.define() on the FIXTUREs
 |FIXTURE_ARR[, ADDITIONS])->MOCKS#ADDITIONS can be FUNC(FIXTURE)->FIXTURE, or FIXTURE_ARR (merged)
MOCKS.done()                      #Like Nock SCOPE.done()
MOCKS.isDone()->BOOL              #Like Nock SCOPE.isDone()
MOCKS.pending()->STR_ARR          #Like Nock SCOPE.pendingMocks()
MOCKS.explain(ERROR)              #To use as ERROR handler, for an HTTP request error
                                  #Noop unless ERROR is due to not matching any Nock SCOPE
                                  #Sets ERROR.message, to indicate which part of request did not match
                                  #Deletes ERROR.config|request|response|status[Code]|source

FIXTURES ==>                      #
get-organization                  #GET OORG
get-repository                    #GET RREPO
get-root                          #GET /
create-file                       #PUT RREPO/contents/test.txt
get-content                       #GET RREPO/contents (DIR) + GET RREPO/contents/README.md (regular FILE)
get-archive                       #GET RREPO/tarball/main
markdown                          #POST /markdown
                                  #POST /markdown/raw
release-assets                    #GET RREPO/releases/tags/TAG
                                  #GET RREPO/releases/ID/assets
                                  #DELETE RREPO/releases/ID/assets/ID2
                                  #POST UPLOAD_URL
release-assets-conflict           #Same with some conflict on POST UPLOAD_URL
git-refs                          #GET|POST RREPO/git/refs
                                  #PATCH|DELETE RREPO/git/refs/heads/test
branch-protection                 #GET|PUT|DELETE RREPO/branches/main/protection
rename-repository                 #PATCH|GET RREPO
add-and-remove                    #PUT|DELETE RREPO/collaborators/NAME
 -repository-collaborator         #GET RREPO/collaborators
labels                            #GET|POST RREPO/labels
                                  #GET|PATCH|DELETE RREPO/labels/NAME
add-labels-to-issue               #POST RREPO/issues/ID/labels
lock-issue                        #PUT|DELETE RREPO/issues/ID/lock
search-issues                     #GET RREPO/issues?q=STR
paginate-issues                   #GET RREPO/issues?per_page=3, repeated
project-cards                     #POST|GET /projects/columns/ID/cards
                                  #GET|PATCH|DELETE /projects/columns/cards/ID
                                  #POST /projects/columns/cards/ID/moves
create-status                     #POST RREPO/statuses/HASH twice (with failure|success)
                                  #GET RREPO/commits/HASH/statuses
                                  #GET RREPO/commits/HASH/status
mark-notifications-as-read        #PUT /notifications
errors                            #POST RREPO/labels with invalid payload

                                  ┌──────────────┐
                                  │   CONTENTS   │
                                  └──────────────┘

GET RREPO/contents/PATH           #Retrieve either:
                                  #  - file contents
                                  #     - max 100MB
                                  #  - DIR's files
                                  #     - max 1000: if more, should use Git trees endpoints instead
                                  #  - symlink
                                  #  - submodule
                                  #Def PATH: root
?ref=COMMIT|BRANCH|TAG            #Def: REPO's default BRANCH

PUT RREPO/contents/PATH           #Upsert REPO file contents
REQ.content                       #'BASE64'
REQ.sha                           #'HASH'. Optional when creating.
REQ.branch                        #'BRANCH' (Def: REPO's default)
REQ.message                       #'COMMIT_MESSAGE'
REQ.author                        #USER
REQ.committer                     #USER
RES.content                       #XFILE
RES.commit                        #XCOMMIT

DELETE RREPO/contents/PATH        #Delete REPO file
REQ|RES.*                         #Like PUT RREPO/contents/PATH except no content

XFILE.path                        #'PATH'
XFILE.name                        #'FILENAME'
XFILE.size                        #NUM (in bytes). 0 if DIR
XFILE.sha                         #'HASH'
XFILE._links.self
XFILE.url                         #'RREPO/contents/PATH'
XFILE._links.html
XFILE.html_url                    #'RREPO/contents/blob/BRANCH/PATH'
XFILE._links.git
XFILE.git_url                     #'RREPO/contents/git/blobs/HASH'
XFILE.download_url                #'https://raw.githubusercontent.com/USER/REPO/BRANCH/PATH'

XFILE.type                        #'file|dir|symlink|submodule'
XREGULAR_FILE.content             #'BASE64'
XREGULAR_FILE.encoding            #'base64'
XDIR.entries                      #RES_ARR
XSYMLINK.target                   #'PATH'
XSUBMODULE.submodule_git_url      #'git://...'

@octokit/                         #Version 5.1.1
 plugin-create-or-update-text-file#Node/Deno/browsers
createOrUpdateTextFile            #PLUGIN

OCORE.createOrUpdateTextFile      #Upsert|delete a REPO regular file (text, not binary)
 (OPTS)->>RES                     #Calls and returns PUT|DELETE RREPO/contents/PATH
                                  #Also calls GET RREPO/contents/PATH
composeCreateOrUpdateTextFile
 (OCORE, OPTS)->>RES              #Same but does not require adding the PLUGIN to OCORE

OPTS.content                      #STR (PUT) or null (DELETE)
                                  #Can be a FUNC(OBJ)->VAL, with OBJ: exists BOOL, content STR
OPTS.*                            #Like REQ.* or PUT|DELETE, except sha is not needed
OPTS.branch                       #Like ?ref of GET

RES.updated                       #BOOL. Whether either deleted, created, or updated with new content
RES.deleted                       #BOOL
RES.content                       #STR. Only if RES.updated && !RES.deleted
RES.*                             #From OREQUEST(...)
                                  #Empty if no change

                                  ┌────────────────────┐
                                  │   CLOUDFORMATION   │
                                  └────────────────────┘

cloudformation-github-resource   ##CloudFormation ETYPEs (extension types) for GitHub API
 -providers                      ##Not documented yet
cloudformation-gitlab-resource
 -providers                      ##Same for GitLab