API 設計總覽

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

在「設計」階段,您可以定義 API 的需求。身為 API 設計人員,您會規劃要向消費者呈現的服務,並設計 API 來存取這些服務。建立下列其中一種文件來擷取 API 需求:

  • OpenAPI 文件
  • GraphQL 結構定義

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

OpenAPI 規格是什麼?


「OpenAPI 倡議計畫 (OAI) 著重於根據 Swagger 規範,建立、改進和宣傳供應商中立的 API 說明格式。」如要進一步瞭解 OpenAPI 計畫,請參閱 https://openapis.org

OpenAPI 文件使用標準格式來描述符合 REST 樣式的 API。以 JSON 或 YAML 格式編寫的 OpenAPI 文件不僅可供機器讀取,也能讓使用者輕鬆閱讀及理解。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 Initiative 網站,您可以在該網站找到總覽、網誌和 OpenAPI 規範的連結。請參閱「規格」中,結構定義元素和資料類型的詳細說明。

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

什麼是 GraphQL 結構定義?

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

使用 GraphQL 的好處包括:

  • 單一端點可讓您存取特定作業的所有欄位
  • 「結構定義定義語言」是功能強大的查詢語言,可協助您完全存取所需資料,避免資料過度擷取或未擷取到
  • 查詢處理作業同時進行

如要進一步瞭解 GraphQL,請參閱 graphql.org

以下範例提供 GraphQL 結構定義,可定義資料進入點 (查詢類型)、可用的寫入作業 (Mutation 類型) 和資料類型。

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 參考說明文件。這個快照代表規格儲存庫中說明文件的特定修訂版本。