[ADP-307] Inspiring URI Design Collection

This document presents a collection of exemplary URI designs observed in public API documentation, serving as inspiration for API designers. Please contribute additional examples when you encounter noteworthy API designs.

Pattern: Non-pluralized Path

GitHub

meta/get

Get GitHub meta information
GET /meta

Description
Returns meta information about GitHub, including a list of GitHub's IP addresses. For more information, see "About GitHub's IP addresses."

• The API endpoint is neither a collection nor a "resource".

meta/get-all-versions

Get all API versions
GET /versions
Get all supported GitHub API versions.

Responses
[
  "2021-01-01T00:00:00.000Z",
  "2021-06-01T00:00:00.000Z",
  "2022-01-01T00:00:00.000Z"
]

• The API returns an array of strings rather than a collection of resources.

app-hook-config/get

GET /app/hook/config

Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see "Creating a GitHub App."

• None of the path segments are pluralized.

Pattern: Modifier

apps/scope-token

POST /applications/{client_id}/token/scoped

Use a non-scoped user-to-server access token to create a repository scoped and/or permission scoped user-to-server access token. You can specify which repositories the token can access and which permissions are granted to the token. You must use Basic Authentication when accessing this endpoint, using the client_id and client_secret of the GitHub App as the username and password. Invalid tokens will return 404 NOT FOUND.

apps/list-accounts-for-plan

GET /marketplace_listing/plans/{plan_id}/accounts
Returns user and organization accounts associated with the specified plan, including free plans. For per-seat pricing, you see the list of accounts that have purchased the plan, including the number of seats purchased. When someone submits a plan change that won't be processed until the end of their billing cycle, you will also see the upcoming pending change.

apps/list-subscriptions-for-authenticated-user-stubbed

GET /user/marketplace_purchases/stubbed

Lists the active subscriptions for the authenticated user. You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint. OAuth Apps must authenticate using an OAuth token.

activity/list-public-events-for-user

List public events for a user
GET /users/{username}/events/public

List events received by the authenticated user
GET /users/{username}/received_events

List public events received by a user
GET /users/{username}/received_events/public

operationId  
activity/list-received-public-events-for-user

Pattern: Miscellaneous

apps/get-by-slug

GET /apps/{app_slug}

Note: The :app_slug is just the URL-friendly name of your GitHub App. You can find this on the settings page for your GitHub App (e.g., https://github.com/settings/apps/:app_slug).

• The design specifies that the identifier might be a URL-friendly string rather than a meaningless UUID.

apps/get-org-installation

GET /orgs/{org}/installation

Enables an authenticated GitHub App to find the organization's installation information.

org
string
The organization name. The name is not case sensitive.

codes-of-conduct/get-for-repo

GET the code of conduct for a repository
GET /repos/{owner}/{repo}/community/code_of_conduct

Returns the contents of the repository's code of conduct file, if one is detected.

codes-of-conduct/get-conduct-code

GET a code of conduct
GET /codes_of_conduct/{key}

enterprise-admin/list-self-hosted-runner-groups-for-enterprise

List self-hosted runner groups for an enterprise
GET /enterprises/{enterprise}/actions/runner-groups

Lists all self-hosted runner groups for an enterprise.

enterprise-admin/get-allowed-actions-enterprise

GET allowed actions for an enterprise
GET /enterprises/{enterprise}/actions/permissions/selected-actions

Gets the selected actions that are allowed in an enterprise. To use this endpoint, the enterprise permission policy for allowed_actions must be configured to selected. For more information, see "Set GitHub Actions permissions for an enterprise."

activity/list-repos-starred-by-authenticated-user

List repositories starred by the authenticated user
GET /user/starred

Lists repositories the authenticated user has starred.

You can also find out when stars were created by passing the following custom media type via the Accept header: application/vnd.github.star+json.

activity/check-repo-is-starred-by-authenticated-user

Check if a repository is starred by the authenticated user
GET /user/starred/{owner}/{repo}

issues/list-events-for-timeline

List timeline events for an issue
GET /repos/{owner}/{repo}/issues/{issue_number}/timeline

orgs/list-saml-sso-authorizations

List SAML SSO authorizations for an organization
GET /orgs/{org}/credential-authorizations

Listing and deleting credential authorizations is available to organizations with GitHub Enterprise Cloud. For more information, see GitHub's products.

orgs/list-app-installations

List app installations for an organization
GET /orgs/{org}/installations

{
  installations: []
}
// Note: Other collection APIs do not provide the collection as a key

repos/set-admin-branch-protection

Set admin branch protection
POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Adding admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.

repos/merge-upstream

Sync a fork branch with the upstream repository
POST /repos/{owner}/{repo}/merge-upstream

repos/get-latest-pages-build

GET latest Pages build
GET /repos/{owner}/{repo}/pages/builds/latest

repos/get-release-by-tag

GET a release by tag name
GET /repos/{owner}/{repo}/releases/tags/{tag}

Description
Get a published release with the specified tag.

reactions/list-for-issue-comment

List reactions for an issue comment
GET /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions

List the reactions to an issue comment.

Instagram

users/self/requested-by

List the users who have requested this user's permission to follow.
GET /users/self/requested-by

{
  "data": [
    {
      "full_name": "string",
      "id": "string",
      "profile_picture": "string",
      "username": "string"
    }
  ],
  "meta": {
    "code": 0
  },
  "pagination": {
    "next_cursor": "string",
    "next_url": "string"
  }
}

tags/{tag-name}/media/recent

GET a list of recently tagged media.
GET /tags/{tag-name}/media/recent

Get a list of recently tagged media. Use the max_tag_id and min_tag_id parameters in the pagination
response to paginate through these objects.

export interface Request {
    /**
     * Number of users to return.
     */
    count?: number;
    /**
     * A query string.
     */
    q: string;
    [property: string]: any;
}

GitLab

getV3GroupsOwned

GET list of owned groups for authenticated user
GET /v3/groups/owned

Get list of owned groups for authenticated user

getV3ProjectsAll

GET all projects for admin user
GET /v3/projects/all

Description
Get all projects for admin user