良いAPIの返却レスポンス #API

背景

SoftwareDesignの8月号読んでいてAPIの設計についてまとめたいと思った。備忘録。

概要

きれいなAPIとはなにか、という設計方法。

対象

APIとは何か？を知っているけれど「きれいな設計」「きれいなAPI」とは何かを考えたい人

引用、参考元

「SoftwareDesign - Web API の作り方 -」

本編

エンベローブを利用しない

エンベローブとはレスポンスJSONの中に含まれるメタ情報（成功失敗のステータスやエラーコードなど）を指す。
HTTP通信ではエンベローブに相当する情報をステータスやヘッダに書き込める。
情報が被ってしまうため、エンベローブはボディには入れない。

悪い例

{
    "header": {
        "status": "success",
        "errorCode": 0,
    },
    "response": {
        name: "Kona"
    }
}

これは、ヘッダ情報に入っているエンベローブがbodyに入っているため不適。

良い例

{
    "response": {
        name: "Kona"
    }
}

システムの構造をユーザに反映するのは望ましくない

悪い例

{
    "response": {
        "id": 12345,
        "name": "Kona",
        "profile": {
            "birthday": "1993/02/02",
            "gender": "male"
        }
    }
}

良い例

{
    "response": {
        "id": 12345,
        "name": "Kona",
        "birthday": "1993/02/02",
        "gender": "male"
    }
}

日付フォーマットを統一する

APIとして広く利用されるためには、利用者にとって一般的なフォーマットや記号を使うことで、利用時のミスを防ぐことが大切。
日付であれば、様々な表記方法があるが、Web上で一般的に利用される W3C-DTF 形式を用います。
日付のほかには、言語コードであればISO-639(en, ja)、国コードであればISO-3166(US, JP)を用いるのが一般的な表記方法。

種類		サンプル
非推奨	RFC 822(RFC 2822, RFC 5322)	Thu, 29 Mar 2018 08:00:00 GMT
非推奨	RFC 850	Thursday, 29-Mar-2018 08:00:00 GMT
非推奨	UNIX タイムスタンプ	1721781500
推奨	RFC 3339(W3C-DTF)	2018-03-29T17:00:00+09:00

エラー詳細をレスポンスボディに入れる

基本的にエラーかどうかはステータスコードで判別する。ただ、詳細まではステータスコードだけではどうしても表現できない。エラーの詳細として、エラーコードやエラーメッセージをレスポンスボディに埋め込む。

悪い例

HTTP/1.1 400 Bad Request
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/json
Content-Length: 0

エラーの場合、レスポンスボディがない

良い例

HTTP/1.1 400 Bad Request
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/json
Content-Length: 77

{
    "code": 4444,
    "message": "不正な値が入力されました"
}

エラー時にHTMLが返却されないようにする

悪い例

HTTP/1.1 404 Not Found
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/html
Content-Length: 17707

<!DOCTYPE html>
<html lang="ja">
...

エラーの場合、Content-Typeがapplication/htmlになっている

良い例

HTTP/1.1 404 Not Found
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/json
Content-Length: 74

{
    "code": 404,
    "message": "リソースが存在しません。"
}

サービス閉塞時は503 と Retry-Afterを返却する

メンテナンス中など

悪い例

HTTP/1.1 404 Not Found
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/html
Content-Length: 17707

<!DOCTYPE html>
<html lang="ja">
...

エラーの場合、Content-Typeがapplication/htmlになっている

良い例

HTTP/1.1 503 Service Temporary Unavaliable
Server: api.example.com
Date: Sat, 28 Mar 2020 01:57:25 GMT
Content-Type: application/json
Content-Length: 87
Retry-After: Mon, 6, Apr 2020 01:00:00 ...

{
    "code": 503,
    "message": "サービスを利用できません。"
}