Web APIの設計 チェック項目

#はじめに
この記事で扱わないこと
・Web APIとは何か？
・HTTPについての説明や仕様

この記事で扱うこと
・エンドポイント（URI）の設計
・レスポンスデータの設計
・設計変更しやすいWeb APIの設計

#エンドポイントの設計
原則：覚えやすくどんな機能を持つURIなのかが一目でわかる

短く入力しやすいURI
人間が読んで理解できるURI
小文字のみで構成されているURI

https://api.github.com/users

適切なHTTPメソッドを利用しているか

GET /users HTTP/1.1
Host: api.github.com

##リソースにアクセスするためのエンドポイントの設計の注意点
複数形の名詞を利用する
URIで利用する単語は多くのAPIで同じ意味に利用されているものを選んでいるか
URI中にスペースやエンコードを必要とする文字が入っていないか
URI中の単語はハイフンで繋いでいるか

https://api.github.com/users

#レスポンスデータの設計

###データフォーマット
基本的にはJSON形式

###データの内部構造
レスポンスのデータ名はなるべく少ない単語数で表現しているか
レスポンスのデータ名として複数の単語を連結する場合、その連結方法はAPI全体を通じて統一しているか
レスポンスのデータ名として変な省略形を使用していないか
レスポンスのデータ名の単数系/複数形はデータの内容と合っているか

  {
    "login": "mojombo",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://avatars.githubusercontent.com/u/1?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/mojombo",
    "html_url": "https://github.com/mojombo",
    "followers_url": "https://api.github.com/users/mojombo/followers",
    "following_url": "https://api.github.com/users/mojombo/following{/other_user}",
    "gists_url": "https://api.github.com/users/mojombo/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/mojombo/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/mojombo/subscriptions",
    "organizations_url": "https://api.github.com/users/mojombo/orgs",
    "repos_url": "https://api.github.com/users/mojombo/repos",
    "events_url": "https://api.github.com/users/mojombo/events{/privacy}",
    "received_events_url": "https://api.github.com/users/mojombo/received_events",
    "type": "User",
    "site_admin": false
  }

レスポンスデータの内容はクライアントから指定できるようになっているか

http://api.example.com/users/123?fields=name,age

レスポンスデータが配列ではなくオブジェクトになっているか

オブジェクトで包むメリット
・レスポンスデータが何を表しているか分かりやすくなる
・レスポンスデータをオブジェクトに統一できる
・セキュリティ上のリスクを避けることができる（JSONインジェクション）

{
    "friends": [
        {
            "id": 22873,
            "name": "Taro Yamada"
        },
        {
            "id": 63910,
            "name": "Jiro Yamada"
        }
    ]
}

#設計変更しやすいWeb APIの設計
APIをバージョンで管理する

・URIにバージョンを埋め込むパターン

http://api.tumblr.com/v2/blog/good.tumblr.com/info

・クエリ文字列に入れるパターン

http://api-public.netflix.com/catalog/titles/series/70023553?v=1.5

・メディアタイプで指定するパターン

Accept: application/vnd.github.v3+json

#参考
[Web API The Good Parts]
(https://www.amazon.co.jp/Web-API-Parts-%E6%B0%B4%E9%87%8E-%E8%B2%B4%E6%98%8E/dp/4873116864)
[Google JSON style guide]
(http://eiichiroi.github.io/google-styleguide-ja/jsoncstyleguide.xml)
[既存のAPIを調べる]
(https://www.programmableweb.com/)