アプリケーションネットワークについて知る
学習の目的
この単元を完了すると、次のことができるようになります。
- API の仕様駆動開発の利点を説明する。
- OpenAPI 仕様 (OAS) によってどのようにリソース、メソッド、パラメーターが定義されているかを確認する。
- 拡張性と再利用可能性を備えたインテグレーションを可能にする適切に設計された API の役割を認識する。
仕様駆動開発アプローチ
家を建てようとしている場面を想像してみてください。設計図なしで、くぎを打ち始めるでしょうか? おそらく無理でしょう。図面がなければ、戸惑います。そのプロジェクトに加わる誰もが、どうすればよいかわからなってしまいます。この論理は、API にも当てはまります。
コードを記述する前に API を設計すると、その API は構造化され、拡張性が高く、使いやすいものになります。このアプローチは「仕様駆動開発」と呼ばれます。見つけやすく、理解しやすく、使用しやすい、適切に文書化された一貫性のある API をチームが作成するのに役立ちます。
このバッジでは、効率的かつ再利用可能なインテグレーションの作成において、API 設計がいかに重要な役割を果たすかを学習します。また、開発が始まる前に API を定義するための標準化された方法である OpenAPI 仕様 (OAS) についても学びます。API のリソース、メソッド、パラメーター、応答がこの仕様に示されており、開発者、テスター、関係者にとってのブループリントとなります。
API 仕様駆動開発の主な利点
-
開発の加速化: 開発者は定義済みの仕様に基づいて作業するため、推測作業と不整合が減少します。
-
コラボレーションの向上: API のコンシューマーと開発者は、コーディングの開始前に設計の確認と調整を行えます。
-
テストの簡易化: 開発プロセスの早い段階で API のモックとテストを行い、ユーザーのニーズに応えていることを確認できます。
-
再利用可能性の向上: 適切に定義された API はモジュール形式で再利用可能になるため、プロジェクト全体で重複作業が減少します。
単元を進めて行く中で、このアプローチによっていかに API 作成が簡略化し、長期的な成功がもたらされるかを学びます。
API 設計が重要な理由
使用したアプリケーションが思っていたように機能しなかったときのことを思い出してみてください。ライドシェアアプリケーションで間違った乗車場所が表示されたことや、オンライン注文の状況がリアルタイムで更新されなかったことなどがあったかもしれません。たいていの場合、こうした問題は API が適切に設計されていないことで生じます。一貫性のないデータを返す、エラーを適切に処理しない、あるいは拡張性を考慮せずに構築されているといったケースがあります。
API が適切に設計されているとシステム間で信頼性の高い予測可能なやり取りが実現するため、データフローが円滑になり、インテグレーションが想定どおりに機能し、開発者がトラブルシューティングに費やす時間が減少します。
API を綿密に計画せずに設計すると、技術的負債が生じることになります。最初から適切に構造化されていなかったことによる問題の修正、コードのリファクタリング、インテグレーションの再構築に余分な手間が必要になります。金融負債のように、技術的負債は時間と共に蓄積していき、開発の遅延化とコストの増加につながります。
適切に設計された API の影響
-
拡張性: モジュール性とバージョン管理を考慮して設計された API は、既存のインテグレーションを壊すことなく進化させることができます。
-
再利用可能性: 標準化された構造によって API が複数のプロジェクトで再利用できるようになるため、時間と労力の節約につながります。
-
インテグレーションの容易性: 一貫したパターンにより、新しい開発者とチームのオンボーディングに要する時間が短縮します。
-
セキュリティとガバナンスの向上: API が構造化されていると、セキュリティ対策とコンプライアンスポリシーを適用しやすくなります。
OpenAPI 仕様を理解する
API が異なるシステム間で一貫して機能するには、明確なブループリントが必要です。OAS では、そのようなブループリントが提供され、RESTful API を定義するための標準化された方法が示されます。
OAS には、開発者と企業が適切に文書化された使いやすい API を作成するための標準的な方法が定義されています。その構造化された機械可読形式により、明確かつ一貫性があり、インテグレーションの準備が整った API を作成できます。OAS には、いくつかの利点があります。
-
標準化されたドキュメントにより、API のリソース、メソッド、パラメーター、応答の定義を簡単に行えます。
-
コード生成では、Anypoint Code Builder のようなツールで OAS 定義から API 実装を生成できるようにすることで開発が加速化します。
-
モックとテストによって開発者はバックエンドコードを記述する前に API 応答をシミュレーションできるため、開発時間が短縮し、精度が向上します。
-
組み込まれた検証によって API がベストプラクティスに沿ったものになるため、長期的な管理と拡張が容易になります。
OAS により、チームは予測可能性、拡張性、再利用可能性を備えた API を設計できます。その結果、開発者と API コンシューマーの作業効率が向上します。
ベストプラクティスを使用して再利用可能性と拡張性を備えた API を設計する
API 設計において、API の使いやすさ、将来のニーズに対応する拡張性、データ整合性のための安全性を確保する実証済みの 5 つの原則があります。
RESTful の原則に従う: 標準 HTTP メソッドを使用します (データの取得に GET、新規リソースの作成に POST、更新に PUT、削除に DELETE など)。RESTful API を使用することで、インテグレーション間の一貫性が保たれます。
明確な命名規則を使用する: API のエンドポイント名は、汎用名や任意の名前ではなく、説明がなくても直感的にわかる名前である必要があります。
-
避ける:
/getFlightInfo12345
-
使用する:
/flights/{id}
API バージョン管理を使用する: API は、新しい機能の追加や古い機能の廃止に伴い、徐々に変化していきます。後方互換性をサポートし、コンシューマーの機能の中断を最小限に抑えるには、ベース URL に API バージョン番号を含めます。
-
使用しない:
/flights(時間と共に変更が生じる可能性があります)
-
使用する: バージョンを明確に示すために、
https://api.mua.com/v1/flightsとhttps://api.mua.com/v2/flightsを使用します。
一貫性のあるエラーメッセージを返す: 何かしらの問題が起きた場合は、明確なフィードバックが必要です。標準化された HTTP 応答コードを使用すると、トラブルシューティングを行いやすくなります。
-
例: 要求されたリソースが存在しない場合、
404 Not Found応答
-
例: 要求が無効である場合、
400 Bad Request応答
セキュアな手法を使用する: API によって機密データが処理されることが多々あるため、セキュリティを最初から組み込む必要があります。一般的なセキュリティ手法には次のようなものがあります。
- 認証に OAuth 2.0 を使用する
- API キーや JWT トークンを使用してアクセスを制限する
- HTTPS を適用して転送中のデータを暗号化する
メモ
API 全体で一貫性を確保すると、採用が加速化します。開発者はシステムの API を 1 つ理解すれば、ほかの API も簡単に理解できます。
例を見てみる: Mule United Airport における OAS
Mule United Airport (MUA) において、航空会社、ベンダー、空港職員は、フライトのスケジュールから手荷物の追跡まであらゆる業務の調整に API を使用しています。ただし、各航空会社は命名規則、認証メソッド、応答形式が異なる独自の API を使用しているため、インテグレーションは一貫性を持たず、時間がかかり、エラーが生じやすくなっています。
こうした状況を打破するために、MUA は OAS を使用する仕様駆動アプローチを採用しました。各 API の設計と文書化は開発の開始前に RESTful 原則、バージョン管理標準、一貫性のあるエラー処理に従って行われるようになりました。API 仕様は、開発者、テスター、パートナーで共有されるブループリントとして機能します。
結果:
- 航空会社のすべての API が同一のエンドポイント構造に従っています (
/flights/{id}、/baggage/{tracking_number})。
- 認証がサービス間で統一されたため、リスクが低減し、アクセスが簡素化しました。
- 適切に定義された共有 API コントラクトにより、開発者はシステム間でインテグレーションを再利用できます。
OAS 駆動の設計とコラボレーションは、MUA が業務効率の改善、パートナーのオンボーディング時間の短縮、拡張可能なインテグレーションの土台を築くのに役立っています。
まとめ
API の設計によって拡張性と再利用可能性がいかに強固に実現するかを理解したところで、次はそれを可能にするブループリントについて見てみましょう。次の単元では、OAS でリソース、メソッド、パラメーターがどのように定義されているかを学びます。また、開発が始まる前に、こうした構造によって明確さと一貫性がもたらされるしくみも見ていきます。