4.2. OpenAPI ドキュメントの例: Petstore API

オリジナルのソースから仕様を読み取るには、OpenAPI Specification を参照してください。

OAS サイトには、API を定義する OpenAPI ドキュメントの例が複数あります。例を使って学習したい場合は、OAS API チームが作成した Petstore API の例に従うことができます。

Petstore API は非常にシンプルな API です。これは、学習を目的とするものであって、実稼働用ではありません。

Petstore API のメソッド

Petstore API は、4 つのメソッドで構成されています。

  • GET /api/pets: システムからすべてのペットを返す
  • POST /api/pets: ストアに新しいペットを作成する
  • GET /api/pets/{id}: ID に基づき 1 つのペットを返す
  • DELETE /api/pets/{id}: ID に基づき 1 つのペットを削除する

Petstore API は 3scale と統合されるため、認証用に別のパラメーターを追加する必要があります。たとえば、ユーザーキー認証方法では、API 利用者はユーザーキーパラメーターを各リクエストのヘッダーに配置する必要があります。その他の認証方法の詳細は、「認証パターン」を参照してください。

ユーザーキーパラメーター

user_key: {user_key}

user_key は、API 利用者により API へのリクエストで送信されます。API 利用者は、3scale 管理者のデベロッパーポータルでこれらのキーを取得します。キーの受信時に、3scale 管理者は Service Management API を使用して 3scale に対する承認チェックを行う必要があります。

OpenAPI Specification の詳細

API 利用者にとって、cURL 呼び出しで表される API のドキュメントは、以下のようになります。

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"