ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-307] 啟發性 URI 設計集合 ​

本文件展示了從公開 API 文件中觀察到的優秀 URI 設計範例集合，作為 API 設計師的靈感來源。當您遇到值得注意的 API 設計時，請貢獻額外的範例。

模式:非複數路徑 ​

GitHub ​

meta/get ​

http
獲取 GitHub 元資訊
GET /meta

描述
返回關於 GitHub 的元資訊，包括 GitHub 的 IP 地址列表。欲了解更多資訊，請參閱"關於 GitHub 的 IP 地址"。
  • API 端點既不是集合也不是"資源"。

meta/get-all-versions ​

http
獲取所有 API 版本
GET /versions
獲取所有支援的 GitHub API 版本。

回應
[
  "2021-01-01T00:00:00.000Z",
  "2021-06-01T00:00:00.000Z",
  "2022-01-01T00:00:00.000Z"
]
  • API 返回字串陣列而非資源集合。

app-hook-config/get ​

http
GET /app/hook/config

返回 GitHub App 的 webhook 配置。欲了解更多關於為您的應用程式配置 webhook 的資訊,請參閱"創建 GitHub App"。
  • 路徑段中沒有使用複數形式。

模式:修飾符 ​

apps/scope-token ​

http
POST /applications/{client_id}/token/scoped

使用非範圍限定的用戶到伺服器訪問令牌來創建一個倉庫範圍和/或權限範圍的用戶到伺服器訪問令牌。您可以指定令牌可以訪問哪些倉庫以及授予令牌哪些權限。訪問此端點時必須使用基本認證,使用 GitHub App 的 client_id 和 client_secret 作為用戶名和密碼。無效的令牌將返回 404 NOT FOUND。

apps/list-accounts-for-plan ​

http
GET /marketplace_listing/plans/{plan_id}/accounts
返回與指定計劃相關聯的用戶和組織帳戶,包括免費計劃。對於按座位定價,您會看到購買該計劃的帳戶列表,包括購買的座位數。當有人提交計劃變更但直到其計費週期結束才會處理時,您還會看到即將到來的待處理變更。

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

http
GET /user/marketplace_purchases/stubbed

列出已認證用戶的活躍訂閱。您必須使用為已授權您的 GitHub App 的用戶創建的用戶到伺服器 OAuth 訪問令牌來訪問此端點。OAuth 應用程式必須使用 OAuth 令牌進行認證。

activity/list-public-events-for-user ​

http
列出用戶的公開事件
GET /users/{username}/events/public

列出已認證用戶接收的事件
GET /users/{username}/received_events

列出用戶接收的公開事件
GET /users/{username}/received_events/public

操作ID  
activity/list-received-public-events-for-user

模式:其他 ​

apps/get-by-slug ​

http
GET /apps/{app_slug}

注意: :app_slug 只是您的 GitHub App 的 URL 友好名稱。您可以在 GitHub App 的設置頁面找到這個 (例如, https://github.com/settings/apps/:app_slug)。
  • 設計指定標識符可能是 URL 友好的字串,而不是無意義的 UUID。

apps/get-org-installation ​

http
GET /orgs/{org}/installation

使已認證的 GitHub App 能夠找到組織的安裝資訊。

org
string
組織名稱。名稱不區分大小寫。

codes-of-conduct/get-for-repo ​

http
獲取倉庫的行為準則
GET /repos/{owner}/{repo}/community/code_of_conduct

如果檢測到,返回倉庫的行為準則文件內容。

codes-of-conduct/get-conduct-code ​

http
獲取行為準則
GET /codes_of_conduct/{key}

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

http
列出企業的自託管運行器組
GET /enterprises/{enterprise}/actions/runner-groups

列出企業的所有自託管運行器組。

enterprise-admin/get-allowed-actions-enterprise ​

http
獲取企業允許的操作
GET /enterprises/{enterprise}/actions/permissions/selected-actions

獲取企業中允許的選定操作。要使用此端點,企業權限策略的 allowed_actions 必須配置為 selected。欲了解更多資訊,請參閱"為企業設置 GitHub Actions 權限"。

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

http
列出已認證用戶標星的倉庫
GET /user/starred

列出已認證用戶標星的倉庫。

您還可以通過在 Accept 標頭中傳遞以下自定義媒體類型來找出何時創建了星標: application/vnd.github.star+json。

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

http
檢查已認證用戶是否標星了倉庫
GET /user/starred/{owner}/{repo}

issues/list-events-for-timeline ​

http
列出問題的時間線事件
GET /repos/{owner}/{repo}/issues/{issue_number}/timeline

orgs/list-saml-sso-authorizations ​

http
列出組織的 SAML SSO 授權
GET /orgs/{org}/credential-authorizations

列出和刪除憑證授權適用於擁有 GitHub Enterprise Cloud 的組織。欲了解更多資訊,請參閱 GitHub 的產品。

orgs/list-app-installations ​

http
列出組織的應用程式安裝
GET /orgs/{org}/installations

{
  installations: []
}
// 注意: 其他集合 API 不提供集合作為鍵

repos/set-admin-branch-protection ​

http
設置管理員分支保護
POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins

受保護分支在 GitHub Free 和 GitHub Free for organizations 的公共倉庫中可用,在 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有倉庫中可用。欲了解更多資訊,請參閱 GitHub Help 文件中的 GitHub 產品。

添加管理員強制執行需要倉庫的管理員或所有者權限,並且必須啟用分支保護。

repos/merge-upstream ​

http
將 fork 分支與上游倉庫同步
POST /repos/{owner}/{repo}/merge-upstream

repos/get-latest-pages-build ​

http
獲取最新的 Pages 構建
GET /repos/{owner}/{repo}/pages/builds/latest

repos/get-release-by-tag ​

http
通過標籤名稱獲取發布
GET /repos/{owner}/{repo}/releases/tags/{tag}

描述
獲取具有指定標籤的已發布版本。

reactions/list-for-issue-comment ​

http
列出問題評論的反應
GET /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions

列出對問題評論的反應。

Instagram ​

users/self/requested-by ​

http
列出已請求此用戶許可關注的用戶。
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 ​

http
獲取最近標記的媒體列表。
GET /tags/{tag-name}/media/recent

獲取最近標記的媒體列表。使用分頁回應中的 max_tag_id 和 min_tag_id 參數來分頁瀏覽這些對象。

export interface Request {
    /**
     * 要返回的用戶數量。
     */
    count?: number;
    /**
     * 查詢字串。
     */
    q: string;
    [property: string]: any;
}

GitLab ​

getV3GroupsOwned ​

http
獲取已認證用戶擁有的群組列表
GET /v3/groups/owned

獲取已認證用戶擁有的群組列表

getV3ProjectsAll ​

http
# 獲取管理員用戶的所有項目
GET /v3/projects/all

#描述
#獲取管理員用戶的所有項目