API 設計の概要

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

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

OpenAPI 仕様とは

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

Apigee の単純な Hello World サンプルを記述した OpenAPI 仕様の一部を以下に示します。詳細については、GitHub の仕様を確認してください。

swagger: '2.0'
    info:
      description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
      version: 1.0.0
      title: Mock Target API
    host: mocktarget.apigee.net
    schemes:
      - http
      - https
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          produces:
            - text/plain
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              type: string
          responses:
            '200':
              description: Success
      /help:
        get:
          summary: Get help
          operationId: Get help
          description: View help information about available resources in HTML format.
          produces:
            - text/html
          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 を公開するときには、OpenAPI 仕様のスナップショットを取得して API リファレンス ドキュメントを生成します。このスナップショットは、仕様ストア内の仕様の特定バージョンを表します。