API 設計總覽

查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

在設計階段，您會定義 API 的需求。身為 API 設計人員，您必須規劃要向消費者公開的服務，並設計用來存取這些服務的 API。您可以建立下列任一文件，擷取 API 需求：

  • OpenAPI 文件
  • GraphQL 結構定義

以下各節將提供 OpenAPI 和 GraphQL 文件的詳細資訊，以及文件在 API 生命週期中扮演的角色。 如需兩種 API 設計選項的比較，請參閱這篇網誌文章，比較 REST 和 GraphQL。

什麼是 OpenAPI 規格？


「OpenAPI 計畫 (OAI) 著重於根據 Swagger 規格，建立、改進及宣傳各供應商適用的 API 說明格式。」如要進一步瞭解 OpenAPI Initiative，請前往 https://openapis.org。

OpenAPI 文件使用標準格式來描述符合 REST 樣式的 API。OpenAPI 文件是以 JSON 或 YAML 格式編寫，機器可讀取，但使用者也能輕鬆閱讀及理解。OpenAPI 規格可以正式說明 API 元素，例如基本路徑、路徑和動詞、標頭、查詢參數、內容類型、回應模型等等。此外，OpenAPI 文件通常用於產生 API 說明文件。

以下為 OpenAPI 文件的片段，用於說明 Apigee 的簡單 hello World 範例。如需詳細資訊，請參閱 OpenAPI 規格： GitHub。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

有許多有關 OpenAPI 規格的優質資訊來源。建議您從 OpenAPI Initiative 網站開始著手，這裡有總覽、部落格文章和 OpenAPI 規範的連結。如需結構定義元素和資料類型的詳細說明，請參閱「規格」。

您可以從 OpenAPI 規格存放區下載許多 JSON 和 YAML 範例 OpenAPI 文件。

什麼是 GraphQL 結構定義？

GraphQL 結構定義說明 API 中可供用戶端查詢的資料。

使用 GraphQL 的好處包括：

  • 單一端點提供對指定作業所有欄位的存取權
  • 強大的查詢語言稱為結構定義語言，可讓您精確存取所需資料，避免過度或不足擷取資料
  • 處理查詢會同時進行

如要進一步瞭解 GraphQL，請造訪 graphql.org。

以下提供 GraphQL 結構定義範例，其中定義了資料輸入點 (查詢類型)、可用的寫入作業 (變異型類型) 和資料類型。

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

您可以查詢 GraphQL 結構定義，以 JSON 酬載的形式傳回所需的確切資料。

GraphQL 查詢和結果

修改文件會有什麼影響？

每個 OpenAPI 或 GraphQL 文件都是整個 API 生命週期的可靠資料來源。在 API 生命週期的每個階段 (從開發到發布再到監控)，都會使用相同的文件。

編輯或刪除文件時，下列內容會影響以下這一行：

  • 如果編輯文件，必須手動編輯相關構件，包括 API Proxy 以及公開資源的所有 API 產品，然後重新產生 API 參考說明文件，反映文件中實作的變更。
  • 如果刪除文件，則必須手動刪除相關構件 (包括 API Proxy)，並編輯任何 API 產品以刪除相關資源，然後重新產生 API 參考說明文件，反映文件及其資源遭到移除的情況。

如果使用 OpenAPI 文件建立 API Proxy，會怎麼樣？

在 Edge 中，您可以使用 OpenAPI 文件建立 API Proxy。只要按幾下滑鼠，就能取得 API Proxy，自動產生路徑、參數、條件式流程和目標端點。接著，您可以新增 OAuth 安全性、頻率限制和快取等功能。

您可以按照下列各節所述，從 OpenAPI 文件建立 API Proxy：

發布 API 時，您會擷取 OpenAPI 文件的快照，以產生 API 參考說明文件。該快照代表規格儲存庫中說明文件的特定修訂版本。