Web APIの返すJSONはどんなフォーマットが好まれるのか

Web APIの返すJSONのフォーマットは、そのAPIを利用するアプリケーションの開発の難易度(そしてモチベーション)に影響を与えます。ここではメジャーなWeb APIの返すJSONのフォーマットを比べます。

これらのAPIについて調べました。

  • Twitter
  • Facebook
  • Google

TwitterもFacebookもGoogleも似ていますが違うフォーマットを採用しています。

Twitter

正常系

正常系の場合、最上位にオブジェクトが来る場合と、リストがくる場合のふた通りがあります。成功したのか失敗したのかを明示した値はないため、errorというキーがないことと、HTTPステータスコードで正常であると判断をすることになります。

ツイートをした際のレスポンスです。

{
    "coordinates": null,
    "favorited": false,
    "created_at": "Wed Sep 05 00:37:15 +0000 2012",
    "truncated": false,
    "id_str": "243145735212777472",
    "entities": {
        "urls": []
    },
    ...
}

ホームタイムラインを取得した際のレスポンスです。

[
    {
        "coordinates": null,
        "truncated": false,
        "created_at": "Tue Aug 28 21:16:23 +0000 2012",
        "favorited": false,
        "id_str": "240558470661799936",
        "in_reply_to_user_id_str": null,
        "entities": {
            "urls": []
        },
        ...
]

異常系

異常系の場合、最上位がオブジェクトになり、その中のエラーリストがオブジェクトを保持しています。そして、そのオブジェクトがmessageで人間、codeでプログラムが理解しやすい形式で情報を保持しています。

{
    "errors": [
        {
            "message": "Sorry, that page does not exist",
            "code": 34
        }
    ]
}

Facebook

正常系

常に最上位がオブジェクトになっています。こちらも成功か失敗かの情報だけを持った項目はありません。errorというキーの有無で判定できます。

{
    "id": "100001679622862",
    "first_name": "\u57fa\u6a39",
    "gender": "male",
    "last_name": "\u6210\u702c",
    "link": "https:\/\/www.facebook.com\/motoki.naruse",
    "locale": "ja_JP",
    "name": "\u6210\u702c \u57fa\u6a39",
    "username": "motoki.naruse"
}

異常系

Twitterに似ていますが、errorがリストではなくオブジェクトになっています。そしてtypeという項目が増えています。messageとcodeについてはTwitterと同じです。

{
    "error": {
        "message": "Unsupported get request. Please read the Graph API documentation at https:\/\/developers.facebook.com\/docs\/graph-api",
        "type": "GraphMethodException",
        "code": 100
    }
}

Google

GoogleについてはBookのAPIを調べました。

正常系

最上位をオブジェクトにして、その中のitemsという項目にリストで要求された情報を保持しています。

{
    "kind": "books#volumes",
    "totalItems": 526,
    "items": [
        {
            各本の情報
        }
    ]
}

異常系

errorの中にすべての情報が入っています。codeやmessageはTwitterやFacebookと同じ情報を保持しています。

{
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "required",
                "message": "Required parameter: q",
                "locationType": "parameter",
                "location": "q"
            }
        ],
        "code": 400,
        "message": "Required parameter: q"
    }
}

コメント

2015 - 2017 (c) 成瀬基樹