前回の記事では、OpenAPI Specification (OAS) を使用した定義駆動型開発の重要性について詳しく説明し、OpenAPI SpecificationがAPIライフサイクルのさまざまな側面でどのように役立つかについて、さらに記事を続けることをお約束しました。
本シリーズの2回目の記事では、OASがAPIライフサイクルの最初の段階であるAPI設計において、どのように役立つかを深く掘り下げていきます。
API設計とは？
優れたデザインは、モニュメントが驚異になり、製品が素晴らしいものになる理由です。エッフェル塔のようなモニュメントから、これらのクールなドリンクストローのような製品まで、デザインは素晴らしい使いやすさと採用の基礎となり得ます。
APIの世界では、デザインはサーバーとクライアント間の契約をモデル化するものと考えることができます。以前の記事で、私はAPI設計について次の定義をしました。
「APIを設計するとは、APIの消費者がそれをよりよく理解し、使用し、統合するのを助け、同時に効果的に維持するのに役立つ効果的なインターフェースを提供することです。すべての製品には取扱説明書が必要であり、APIも例外ではありません。」
オリジナルの「Swagger」Specificationの作成者であるTony Tamは、API設計には「失敗の計画」が含まれると説明しています。API契約は、社内外の利害関係者が何をすべきか、そして素晴らしいAPIを構築するためにどのように協力できるかを理解するのに役立ちます。
OAS 3.0を使用したAPI設計
OpenAPI Specificationは、APIを設計する最もよく知られた方法の1つです。OASは、APIのインターフェースを記述するために必要なルールと構文を指定します。この記事執筆時点では、OASの第3版です。OASは、現代のAPIチームのニーズを満たすために進化し、仕様をより使いやすく、人間とコンピューターの両方にとって理解しやすくするためのアップデートを導入し続けています。以下は、OAS 3.0を使用してOASで定義されたAPIの一般的な概要です。
上記の図は、OASによって設計されたAPI契約のさまざまなセクションを分解しています。最初は分かりにくいかもしれませんが、各セクションの意味と使用方法を説明します。
情報
infoセクションには、APIの契約に関連するメタデータが含まれています。このセクションの必須項目は、APIのタイトル、バージョン、説明です。このセクションには、連絡先情報、ライセンス情報、サービス利用規約のリンクなどの他のフィールドも指定できます。基本的には、Infoオブジェクトは、APIが何を行うのかについて、消費者と社内開発者の両方に高レベルの概要を提供する必要があります。
openapi: 3.0.0
info
title: Simple Pet Store
version: 1.0.0
description: これはペットストアのサンプルサーバーです。
termsOfService: http://example.com/terms/
contact
name: API Blogger
email: [email protected]
url: http://example.com/support
license
name: Apache 2.0
url: https://apache.dokyumento.jp/licenses/LICENSE-2.0.html
完全なドキュメントはこちらでご確認ください。
サーバー
APIは、コンシューマーとサーバー間の契約です。Serverオブジェクトは、そのURLを介して、APIのサーバーがどこにあるかについての情報をクライアントに提供できます。API定義に1つのサーバーURLのみを許可していた仕様の2.0バージョンとは異なり、OAS 3.0は複数のサーバーをサポートしています。これは、現実世界ではAPIが複数の環境に存在し、環境によって契約のビジネスロジックが変更される可能性があるため、役立ちます。
このセクションの例を以下に示します。
サーバー
- url: http://production.example.com/v1
description: 本番サーバー
- url: http://staging.example.com
description: テスト用のステージングサーバー
完全なドキュメントはこちらでご確認ください。
セキュリティ
今日のデータ機密性の高い世界では、すべてのAPIがある程度のセキュリティを必要とします。OpenAPI記述形式は、不明な未登録ユーザーがAPIにアクセスするのを防ぐために、さまざまな認証および認可スキームをサポートしています。OpenAPIは以下をサポートしています。
- HTTP認証スキーム
- ヘッダー、Cookie、またはクエリ文字列のAPIキー
- OAuth2
- OpenID
API設計にセキュリティを実装するには2つのステップがあります。最初のステップはセキュリティ実装を定義することであり、2番目のステップはそれらを呼び出すことです。このセクションで定義されているSecurityオブジェクトは、実際のセキュリティ定義を呼び出すために使用されます。セキュリティ実装の定義は、後述するComponentsセクションで行われます。
これはSecurityオブジェクトの例です
セキュリティ
- ApiKeyAuth: []
- OAuth2
- read
- write
コンポーネント
ApiKeyAuth
type: apiKey
in: header
name: X-API-Key
上記の例では、ApiKeyAuthがSecurityオブジェクトの下で呼び出されていますが、オブジェクトの実際の定義はコンポーネントオブジェクトの下で行われるべきです。
Securityオブジェクトの詳細については、こちらをご覧ください。
パス
このセクションには、APIが公開するさまざまなエンドポイントと、それに対応するHTTPメソッドが表示されます。また、各メソッドの下には、実際の要求-応答サイクルが詳細に記述されています。要求はParameterオブジェクトによって記述され、応答はResponsesオブジェクトによって記述されます。
パスと操作の詳細については、こちらをご覧ください。
パラメータ
パラメータはリクエストの可変部分です。OAS 3.0を使用して指定できるパラメータには4つのタイプがあります。
応答
レスポンスは、リクエストに対して返されるオブジェクトです。すべてのレスポンスは、そのHTTPステータスコードと返されるデータによって定義されます。使用されるHTTPステータスコードは、リクエストが成功したか失敗したかを定義します。HTTPステータスコードのリストについては、こちらをお読みください。
以下は、簡単なレスポンスの例です。
レスポンス
200:
description: 成功レスポンス
コンテンツ
text/plain
スキーマ
タイプ: 文字列
例: 例文字列はこちら
応答の詳細については、こちらをお読みください。
コンポーネント
APIに対してより多くのリソースと操作を公開すると、契約が非常に長くなる傾向があります。APIは、多くの異なるパスと操作で既存のパラメーターやレスポンスの記述を繰り返す可能性があり、そのたびに書き直すと、記述が矛盾しやすくなり、非常に時間がかかります。
コンポーネントオブジェクトは、APIの設計の再利用可能なオブジェクトのセットを保持できます。再利用可能なオブジェクトには、スキーマ、レスポンス、パラメーター、例などが含まれます。正確な再利用可能なコンポーネントは、任意のパスアイテムで参照できます。
以下は、コンポーネントオブジェクトの例です。
パス
/ペット
取得
概要: すべてのペットを取得
レスポンス
'200':
説明: すべてのペットのリスト
コンテンツ
application/json
スキーマ
タイプ: 配列
アイテム
$ref: '#/components/schemas/Pet"
コンポーネント
スキーマ
ペット
タイプ: オブジェクト
プロパティ
id
型: 整数
例: 65
名前
タイプ: 文字列
例: 犬
年齢
型: 整数
例: 4
コンポーネントの詳細については、こちらをご覧ください。
外部ドキュメント
APIの利用と統合を容易にするために、追加情報を提供することは常に良いアイデアです。OAS 3.0では、外部ドキュメントを参照できます。
説明: 追加情報はここで見つけることができます
url: http://info.here.com
タグ
タグは、さまざまな操作をグループ化するための使いやすいカテゴリです。これにより、APIの利用者はAPIを何に利用したいかをより適切にセグメント化して特定できます。これらのタグは、OASと統合したり読み込んだりする他のサードパーティツールでも処理できます。
タグオブジェクトを使用すると、すべてのパス操作にタグを自動的に追加できます。API定義のルートレベルにオプションのタグセクションを追加することで、各タグの意味をより詳細に記述することもできます。
パス
/pet/findByStatus
取得
概要: ステータスでペットを検索
タグ
- ペット
...
/ペット
投稿
概要: ストアに新しいペットを追加
タグ
- ペット
...
/store/inventory
取得
概要: ペットの在庫を返す
タグ
- ストア
...
タグ
- name: pets
説明: あなたのペットに関するすべて
外部ドキュメント
url: http://docs.my-api.com/pet-operations.html
- name: store
説明: ペットストアの注文へのアクセス
外部ドキュメント
url: http://docs.my-api.com/store-orders.html
タグの詳細については、こちらをお読みください。
もちろん、これはOpenAPIで設計されたAPIに関連するさまざまなセクションの一般的な概要にすぎません。設計は主観的であり、OASはAPIを記述するために必要なルールと項目を提供しますが、それらを効果的に使用してAPIの価値を伝えることが、優れた設計につながります。以前にAPI設計のベストプラクティスについて説明しましたので、ぜひご確認ください。
OAS 3.0と2.0の変更点を知りたい場合は、この録画トレーニングをご覧ください。OASの始め方を知りたい場合は、いつでもこのビデオを参照してください。
API設計のための適切なツール
設計はAPIライフサイクルの中で最も重要な側面の1つであり、それゆえに専用のツールが必要です。SwaggerのOpenAPIエディタは、API設計プロセスを開始するのに最適な方法です。クリーンで効率的で、RESTfulインターフェースを箱から出してすぐに設計するのに役立つ多数の機能を備えています。
- エディターは、ローカルでもウェブでも、あらゆる開発環境で動作します。
- OpenAPI準拠の構文を記述しながら、簡潔なフィードバックとエラー処理で検証
- API仕様を視覚的にレンダリングし、定義しながらAPIと対話します。
API設計で共同作業をしたい場合は、いつでもSwaggerHubを試すことができます。SwaggerHubは、チームがAPIを一貫した標準化された方法で設計するためのAPI開発プラットフォームです。SwaggerツールエコシステムとOASを組み合わせることで、API設計のレベルをさらに向上させることができます。
お読みいただきありがとうございます！さらにAPIリソースをお探しですか？Swaggerニュースレターを購読してください。最高のAPI記事、トレーニング、チュートリアルなどを毎月メールでお届けします。 購読する