API 設計總覽

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

  • OpenAPI 說明文件
  • GraphQL 結構定義

以下各節將進一步說明 OpenAPI 和 GraphQL 文件，以及這些文件在 API 生命週期中扮演的角色。如要比較這兩種 API 設計選項，請參閱這篇網誌文章。

什麼是 OpenAPI 規格？


「OpenAPI 計畫 (OAI) 的重點是根據 Swagger 規格，建立、發展及推廣與供應商無關的 API 說明格式。」如要進一步瞭解 OpenAPI 計畫，請參閱 https://openapis.org。

OpenAPI 說明文件會使用標準格式說明 RESTful API。OpenAPI 文件可採用 JSON 或 YAML 格式，不僅可供機器讀取，也方便人類閱讀及理解。OpenAPI 規格可正式描述 API 的元素，例如基本路徑、路徑和動詞、標頭、查詢參數、內容類型、回應模型等。此外，OpenAPI 文件通常用於產生 API 說明文件。

以下是 OpenAPI 文件中的片段，說明 Apigee 的簡單 Hello World 範例。如需更多資訊，請前往 GitHub 查看 OpenAPI 規格。

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 計畫網站，瞭解相關總覽、部落格和 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 查詢和結果

如果我修改文件，會怎麼樣？

在整個 API 生命週期中，每個 OpenAPI 或 GraphQL 文件都是可靠資料來源。從開發、發布到監控，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 參考文件。該快照代表規格儲存庫中說明文件的特定修訂版本。