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}"