はじめに
この記事で扱わないこと
・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