モック対応 API について詳しく学ぶ
学習の目的
この単元を完了すると、次のことができるようになります。
- OpenAPI 仕様 (OAS) における完全な API 定義の要素を確認する。
- クエリパラメーターと応答例によって API のテストと確認がどのように簡易化するかを説明する。
- API 構造によってモックと早期の関係者フィードバックがどのように支えられるかを説明する。
- テストと関係者による確認に向けて、API がどのように準備されるかを説明する。
目的に基づく設計
優れた API に必要な要素について学びました。その要素とは、明確に定義されたリソース、再利用可能な構造、そして予測可能な動作です。次は、こうした要素が完全な API 設計にどのようにまとめられるかを詳しく見てみましょう。
すぐにバックエンドロジックや本番リリースに進むわけではないですから安心してください。ここで焦点を当てるのは、API がどのように動作すべきかを実装前に定義する仕様ファーストの設計というベストプラクティスです。
なぜそれが役立つのでしょうか?
最初に API を設計すると、次のことが可能になるからです。
- 構造を早期に検証できる。
- ほかのチームが確認してフィードバックを行うことができる。
- バックエンドコードを記述し始める前に、動作をモックしてテストすることができる。
この単元では、OpenAPI 仕様 (OAS) を使用して作成された完全に構造化された API 定義のガイド付きの例を見ていきます。また、この段階でどのような設計上の選択を行えば、ジャーニーの次のステップにおけるテストと関係者による確認に向けて API の準備が整うのかも確認します。
Mule United Airport が Flights API を設計する
Mule United Airport では、予約可能なフライトを社内チームとパートナーチームが見つけることができるようにするための新しいエンドポイントを API チームが設計します。この初期の API バージョンは、バックエンドコードが記述される前に確認、テスト、モックすることができるように OAS を使用して定義されます。
API を定義する方法
API 定義の構造は次のとおりです。
- ベースパスとリソース:
/flightsは、フライトデータが要求されるエンドポイントを表します。 - HTTP メソッド:
GETメソッドによってフライトのリストを取得します。 - クエリパラメーター:
destinationという名前のパラメーターを使用すると、都市コードによる絞り込みが可能になります。 - 応答例: JSON サンプルペイロードにより、API で返されるデータ構造が示されます。
仕様例 (YAML)
# OpenAPI specification version
openapi: 3.0.0
info:
# Metadata about the API
title: American Flights API
version: 1.0.0
paths:
/flights:
get:
# Summary of what this operation does
summary: Retrieve a list of flights
# List of inputs that can be passed to the API operation
parameters:
- in: query # Specifies that the parameter is passed in the query string of the URL
name: destination # The name of the query parameter (e.g., /flights?destination=SFO)
schema:
type: string # The expected data type of the parameter
description: Filter flights by destination
responses:
'200':
# Description of the response
description: A list of flights
content:
application/json:
# Sample JSON response body
example:
- flightNumber: AA123
destination: SFO
エラーの設計
API 定義に成功したパスしか記述されていない場合、完全ではありません。コンシューマーは、何らかの問題が発生したときの処理も知る必要があります。API 設計には、開発者が一貫した方法で問題を予測して処理できるように、標準化されたエラー応答を含める必要があります。
たとえば、「American Flights API」には次のような応答が含まれる可能性があります。
'400':
description: Invalid request
content:
application/json:
example:
error: "Bad Request"
message: "The destination code is missing or invalid"
'404':
description: Flight not found
content:
application/json:
example:
error: "Not Found"
message: "No flights match the request"
'500':
description: Internal server error
content:
application/json:
example:
error: "Server Error"
message: "An unexpected error occurred. Please try again later."API 定義に成功応答とエラーケースの両方が示されている場合、次のことが可能になります。
- 開発者の明確な期待事項を設定する
- 一般的なシナリオを使用することでテストが現実的なものになる
- チームとエンドポイント全体で一貫性が促される
エラー処理が設計フェーズに含まれている場合、開発時の想定外の事態が減り、API プロデューサーとコンシューマー間のコラボレーションが向上します。
ツールが役立つしくみを知る
Anypoint Code Builder のようなツールでは、エディターに構文の強調表示、オートコンプリート、エラーを検出するのに役立つリアルタイム検証が用意されています。API コンソールのプレビューでは、関係者向けのテスト可能なビューに仕様を表示することもできます。
モック対応 API のチェックリストを使用する
完全な API 定義には、テストを可能にし、簡単に確認できるようにするためのあらゆる詳細が含まれています。次のチェックリストを使用して、必須要素が揃っていることを確認してください。
- リソースとエンドポイントが明確に定義されている
- メソッドが各リソースに関連付けられ、使用可能なアクションが記述されている
- 要求の絞り込みや調整を行うためのパラメーターが含まれている
- 想定されるデータ構造が応答例に示されている
- 何らかの問題が発生した場合の処理がエラー応答に記述されている
- 一貫性のある命名規則と標準化された形式によって、設計の予測可能性が維持されている
バックエンドコードが記述される前に上記の要素が揃っている場合、API は明確で、簡単にテストできる状態になっており、モック、関係者による確認、早期フィードバックにいつでも対応できます。
まとめ
実装前に API を設計すると、チームは早期にコラボレーションし、エスカレーションする前に問題を検出し、想定される API 動作について認識を合わせることができます。
次の単元では、サンプル要求とサンプル応答を使用して、モックの準備が整った API のテストと確認をどのように行えるかを学びます。この手法を使用すると、バックエンドコードが記述される前に、関係者からフィードバックを得て、設計が堅固であることを確認することができます。