OAS を使用して API を定義する
学習の目的
この単元を完了すると、次のことができるようになります。
- OpenAPI 仕様 (OAS) によって API 設計のブループリントがどのように提供されるかを説明する。
- OAS ベースの設計によってチーム間の一貫性、拡張性、コラボレーションがどのように向上するかを説明する。
- リソース、メソッド、パラメーターなどの主な API コンポーネントを確認する。
Anypoint Code Builder を使ってみる
前の単元では、適切に構造化された API によって、どのようにインテグレーションが拡張性と再利用可能性を備え、管理が容易になるかを学習しました。では次に、その原則がどのように API の設計に適用されるのかを詳しく見ていきましょう。
OpenAPI 仕様 (OAS) は、コードを記述する前に API を記述するための標準化された方法です。API でサポートされるリソース、メソッド、パラメーター、応答を示す機械可読形式が提供されています。OAS により、開発者と関係者はプロセスの早い段階で設計の確認、フィードバックの提供、一貫性の確認を行うことができます。
OAS により、次のことが可能になります。
- 予測可能な形式で、API のリソース、メソッド、パラメーターを定義する。
- 開発が開始する前に、API がベストプラクティスに従っていることを検証する。
- 応答をシミュレーションして、設計精度のテストとフィードバックの収集を行う。
- チーム間で仕様を共有し、ディスカバリーと再利用を向上する。
この単元では、リソース、メソッド、パラメーター、再利用可能なコンポーネントなどの API 設計の基本要素が OAS でどのように示されているかを確認します。また、一貫性のある共同的な API 開発を支えるために、こうした要素がどのように連携して機能しているかを学びます。
リソースを定義する
すべての API の中核となるのは、リソースのセットです。これは、クライアントがやり取りできるシステムの個別の要素です。OAS では、リソースは API が公開するデータの種別や機能を示す URL パスを使用して定義されます。
たとえば、フライト予約 API のリソースには次のようなものが含まれます。
/flights– 予約可能なフライトのリスト/flights/{id}– 特定のフライトについての詳細/passengers/{passenger_id}/bookings– 乗客の予約
各リソースは、特定のタスクまたはデータ型に焦点が当てられています。これは、まさに求めているものを開発者が見つけて使用するのに役立ちます。
Anypoint Code Builder などのツールでは、API の構造の一部としてリソースを表すために OAS を使用します。リソースを定義したら、ユーザーによる API の操作方法を指定するメソッドとパラメーターを追加できます。
メソッドとパラメーターを追加する
API 設計の最初のステップは、リソースを定義することです。ただし、API を有用なものにするには、API でどのようなアクションを実行できるかと、クライアントでそのアクションをどのように調整できるかも指定する必要があります。ここで登場するのがメソッドとパラメーターです。
OAS では、HTTP メソッドによってリソースへのアクセス方法が定義されています。
GET: データを取得する (たとえば、フライトリストの取得)。POST: 新しいリソースを作成する (たとえば、フライトの予約)。PUT: 既存のリソースを更新する (たとえば、予約の変更)。PATCH: 既存のリソースの一部を更新する (たとえば、予約における座席番号のみの変更)。DELETE: リソースを削除する (たとえば、予約のキャンセル)。
要求の具体性と柔軟性を高めるには、API でパラメーターを使用します。
- パスパラメーターは、URL パスの特定のリソースを識別するのに役立ちます。中括弧で囲まれます。たとえば、
/flights/{id}では、idがパスパラメーターです。多くの場合は必須ですが、API 設計に応じて省略できる場合があります。 - クエリパラメーターは URL 内のクエスチョンマーク (
?) の後ろに続き、 要求の絞り込み、または調整を行います。各クエリパラメーターでは値の割り当てに等号 (=) を使用し、複数のパラメーターはアンパサンド (&) で区切ります。例:/flights?departure=JFK&destination=LAX
メソッドとパラメーターが重要な理由
明確なメソッドとパラメーターがなければ、API の使用と管理は困難になります。たとえば、API にクエリパラメーターが含まれず /flights エンドポイントしかない場合、すべての要求はユーザーの検索に一致するものだけでなく、すべてのフライトを返してしまいます。DELETE 操作がない場合は、管理システムで古いフライトやキャンセルされたフライトを航空会社のスケジュールから削除できません。
メソッドとパラメーターが明確に定義されていると、API はより直感的かつ効率的となり、柔軟性も備わります。API 応答を軽量でパフォーマンスの高いものに維持しながら、アプリケーションで適切なデータをすばやく取得できるようになります。
再利用を考慮して設計する
API は長持ちするように作成する必要があります。新機能のたびに大規模な変更が必要になったり、類似タスクのために異なるチームが個別の API を作成する必要が生じたりすると、あっという間に収拾がつかなくなります。再利用可能な API 設計を行うと、既存のインテグレーションを壊すことなく将来の更新に対処できる柔軟性が保たれ、こうした問題が回避されます。
再利用可能性により、管理の低減、開発の迅速化、インテグレーションの拡張性の向上が実現します。
再利用可能な API のベストプラクティス
ビジネスニーズの変化に合わせて有用性を維持する API を設計するには、次のベストプラクティスに従います。
- 一貫した命名規則を使用する。 予測可能な構造により、API がわかりやすく、操作しやすいものとなります。あるエンドポイントが
/getFlightInfoで、別のエンドポイントが/bookings/{id}である場合、開発者は明確な論理形式に従う代わりに、パターンを推測しなければならなくなります。 - データ構造とパターンを標準化する。 乗客の詳細、認証、エラー処理のようなものには、一貫した項目名と応答形式を使用します。こうすると、チームがインテグレーションをより速く構築し、長期にわたって維持するのに役立ちます。
- 適切に API のバージョンを管理する。変更は必然的ですが、既存のインテグレーションを壊さないようにする必要があります。バージョン管理 (
/v1/flights、/v2/flights) を行うと、異なるバージョンが共存できるため、コンシューマーは移行するための時間を確保できます。 - API の動作を詳細に文書化する。 API を適切に文書化すると、開発者がインテグレーションを速め、コストのかかる再作業やエラーにつながる可能性のある誤解を防ぐのに役立ちます。
こうしたガイドラインにより、開発者が常にインテグレーションを記述し直さなくても、API を変化するニーズに適用できるようになります。
Mule United Airport が拡張性 API を作成する
Mule United Airport では、それぞれニーズが異なる複数のグループがフライト予約 API を使用しています。
- 乗客は、日付と出発都市でフライトを検索し、航空券を予約します。
- 航空会社の職員は、フライトスケジュールを更新し、予約可能な座席を確認します。
- 運用チームは、リアルタイムでフライトの状況とゲートの割り当てを監視します。
明確なメソッドとパラメーターを含む適切に構造化された API を使用すると、各チームに必要なデータのみが提供され、不必要な要求でシステムがオーバーロードされることがなくなります。
MUA は各チームに個別の API を作成する代わりに、複数のユースケースをサポートする柔軟な API を 1 つ設計します。このモジュール式アプローチにより、手荷物の追跡やロイヤルティプログラムの統合のような新機能が既存の機能に支障をきたすことなく追加できます。
MUA のチームは適切に構造化された API で始めたため、重複作業の回避、管理オーバーヘッドの削減、将来の拡張性へのサポートを実現できています。
まとめ
これで、OAS を使用する API 設計の主要要素を理解できました。リソースの定義、メソッドとパラメーターの追加、そして、例と一貫性のある設計パターンによって明確性を改善する方法を学びました。
Anypoint Code Builder のようなツールには API の構造化と整理を効果的に行うための環境が用意され、こうした原則をサポートしています。
次の単元では、完全な API 仕様を見ていきます。また、開発ツールに実際にアクセスする必要なくモックと関係者の確認を行うために、その構造がどのように役立つかも学習します。