API 設計の概要

設計フェーズで API の要件を定義します。API デザイナーは、コンシューマに公開するサービスを計画し、それらのサービスにアクセスするための RESTful API を設計します。読みやすい JSON または YAML 形式で OpenAPI 仕様を作成して、API 要件をその中に取り込みます。

以降のセクションでは、OpenAPI 仕様について、またこの仕様が API のライフサイクルで果たす役割について詳しく説明します。

OpenAPI 仕様とは

「Open API Initiative（OAI）は、Swagger 仕様に基づく、ベンダーに依存しない API 記述形式の作成、進化、促進に注力しています。」Open API Initiative について詳しくは、https://openapis.org をご覧ください。

OpenAPI 仕様では、標準的な形式を使用して RESTful API を記述します。JSON または YAML 形式で記述された OpenAPI 仕様は、マシン可読でありながら、人間も簡単に読んで理解できます。この仕様では、ベースパス、パスと動詞、ヘッダー、クエリパラメータ、コンテンツタイプ、レスポンスモデルといった API の要素が記述されます。また、OpenAPI 仕様は API ドキュメントの生成にもよく使用されます。

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 仕様に関する多くの優れた情報源があります。まず出発点として役立つサイトは Open API Initiative です。このサイトには、概要、ブログ、OpenAPI 仕様のリンクが掲載されています。スキーマ要素とデータタイプの詳細な説明については、仕様を参照してください。

さまざまな JSON と YAML のサンプル仕様があり、OpenAPI 仕様リポジトリからダウンロードできます。

仕様を変更するとどうなるか

それぞれの OpenAPI 仕様は、API ライフサイクル全体の基礎となる事実として機能します。開発から公開、さらにモニタリングに至るまで、API ライフサイクルのすべてのフェーズで同じ仕様が使われます。

OpenAPI 仕様を編集または削除すると、次のような直接的な影響があります。

仕様を編集した場合、API プロキシなどの関連アーティファクトや、そのリソースを公開する API プロダクトを手動で編集する必要があります。また、仕様に実装された変更を反映するように API リファレンスドキュメントを作り直す必要もあります。
仕様を削除した場合、API プロキシなどの関連アーティファクトを手動で削除し、API プロダクトを編集して関連リソースを削除する必要があります。また、仕様とそのリソースの削除を反映するように API リファレンスドキュメントを作り直す必要があります。

OpenAPI 仕様から API プロキシを作成するとどうなるか

Edge では、OpenAPI 仕様から API プロキシを作成できます。数回クリックするだけで、パス、パラメータ、条件付きフロー、ターゲットエンドポイントが自動生成された状態の API プロキシができます。その後、OAuth セキュリティ、レート制限、キャッシュなどの機能を追加できます。

以降のセクションに示す方法で、OpenAPI 仕様から API プロキシを作成できます。

仕様リストから（仕様リスト内の仕様から API プロキシを作成するを参照）。注: Classic Edge では仕様リストを使用できません。
API プロキシマネージャーから。その際、[Build Proxy] ウィザードを起動し、OpenAPI 仕様から API プロキシを作成することを選択します（OpenAPI 仕様を使用したプロキシの生成を参照）。

API を公開するときには、OpenAPI 仕様のスナップショットを取得して API リファレンスドキュメントを生成します。このスナップショットは、仕様ストア内の仕様の特定バージョンを表します。