【技術ブログ】オリジナルのWeb API 設計の知識 vol.3 ：レスポンス設計

開発エンジニアのNAHO.Sです。

前回の記事（vol.2）ではエンドポイントに関する内容を記載しました。
本記事ではWeb APIにおける「レスポンス設計」として、レスポンスの種類や設計例について記載します。

APIレスポンスとは、リクエスト内容に基づいてAPI利用者へ返されるデータや値のことを指します。
レスポンスは、APIの使いやすさや信頼性に直結する重要な要素です。
適切に設計することで、エラー原因の特定がしやすくなり、開発効率やサービスの品質向上にもつながります。

３.レスポンス設計

3.1. レスポンスデータの種類

レスポンスデータの形式は、JSONとXMLが有名です。
JSONの方がモダンなWeb開発において多く採用されており、パフォーマンスも軽量のため、特別な理由がない限り、JSONを選択したほうが無難です。

主な違いとして、以下があります。

3.2. ステータスコード

ステータスコードは、リクエストの結果を示す3桁の数字です。
これにより、クライアントはリクエストが成功したか、失敗したか、あるいは追加のアクションが必要かを判断することができます。

一般的には以下で定義されています。
以下のほかにも独自でステータスコードを用意してやり取りすることも可能です。

3.3. ヘッダー

ヘッダーは、レスポンスのメタデータを含むキーと値のペアの集合です。
これにより、クライアントはレスポンスの内容や形式についての追加情報を取得できます。

• Content-Type：レスポンスのボディーのメディアタイプ
• Date：レスポンスが送信された日時
• Cache-Control：キャッシュの動作を制御する内容

ヘッダーの例

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Tue, 25 Dec 2024 12:34:56 GMT
Cache-Control: max-age=3600
Content-Length: 123
Server: MyCustomServer/1.0

3.4. ボディー

ボディーは、レスポンスのメインコンテンツ部分です。
メインコンテンツには商品に関する情報(商品のID、商品名、価格など)が含まれています。
主にクライアントがリクエストしたデータや通信情報が含まれます。

ボディーの例は次項で紹介します。

3.5. レスポンス例

レスポンスの例を成功時と失敗時に分けて紹介します。
以下は、成功例のレスポンスで使用する項目の説明です。

成功時：指定したカテゴリに3件の商品があった場合

{
   "statusCode": 200,
   "totalCount": 3,
   "products": [
       {
           "productId": 12345,
           "name": "スマートフォン",
           "price": 299.99,
           "description": "高性能なスマートフォンです。"
       },
       {
           "productId": 12346,
           "name": "ノートパソコン",
           "price": 999.99,
           "description": "プロフェッショナル向けの強力なノートパソコンです。"
       },
       {
           "productId": 12347,
           "name": "ヘッドフォン",
           "price": 199.99,
           "description": "ノイズキャンセリング機能付きのヘッドフォンです。"
       }
   ]
}

成功時：指定したカテゴリに商品が無かった場合

商品が無かった場合でも、成功時と同様にすべての項目を返すようにしましょう。
項目ごと削除してしまうと、プログラム側で精査が必要になってしまいます。
そのため、項目自体はすべて残して、空かNullを返すようにしましょう。

{
   "statusCode": 200,
   "totalCount": 0,
   "products": []
}

NG例：指定したカテゴリに商品が無かった場合

{
   "statusCode": 200,
   "totalCount": 0,
}

NG例：記載がない項目は、項目自体を返さない

{
   "statusCode": 200,
   "totalCount": 2,
   "products": [
       {
           "productId": 12345,
           "name": "スマートフォン",
           "description": "高性能なスマートフォンです。"
       },
       {
           "productId": 12346,
           "name": "ノートパソコン",
           "price": 999.99,
       }
   ]
}

以下は、失敗例のレスポンスで使用する項目の説明です。

エラー時(存在しないカテゴリを指定した際)

エラー時にはエラーが分かるメッセージを合わせて返すようにします。
エラーに関する概要と、詳細等、エラーを特定できる内容を項目として利用します。

{
   "statusCode": 404,
   "error": "カテゴリーが見つかりません",
   "message": "指定されたカテゴリー 'xxxxx' は存在しません。"
}

まとめ

今回の記事ではレスポンスにおけるレスポンスデータの解説から、レスポンス例までをご紹介しました。
次回の記事では、セキュリティ設計についてご紹介します。

上記の記事に関してご質問ございましたら、お問い合わせください。