オライリーのWebAPIを参考にAPIの設計に関するスライドを作りました。

1. APIの設計ってどうやるの？
鈴木 雄登

2. APIの種類

3. • よく使われるAPIの利用目的
– 公開しているWebサービスへのアクセス用API
– 他のページに貼り付けるウィジェット
– AJAXを駆使したページ用のAPI
– スマホアプリ用のAPI
– ソシャゲ用のAPI
– 社内システムとの連携API

4. こんなサービスも
Programmable Web

5. こんなサービスも
Programmable Web

6. でもAPIの設計って
あんまり解説してない

7. アジェンダ
• APIの設計を始める前に
• エンドポイントの設計
• レスポンスデータの設計

8. APIの設計を始める前に

9. 設計に入る前に決めるべきこと
• 何をAPIで公開するのか？
– 全データのAPIを作るのか？
– 全てのAPIを作るのは、時間がかかるが、ユーザ
も増え思いがけないメリットも見つかる
• 誰を対象にしたAPIか？
– ユーザを想定しなければ、使いやすいAPIというも
のは作れない

10. 設計に入る前に決めるべきこと
• 何をAPIで公開するのか？
– 全データのAPIを作るのか？
– 全てのAPIを作るのは、時間がかかるが、ユーザ
も増え思いがけないメリットも見つかる
• 誰を対象にしたAPIか？
– ユーザを想定しなければ、使いやすいAPIというも
のは作れない

11. アプリケーションを作るのと同じで、
誰に向けた設計かを意識するだけで、
使いやすさは全然変わってくる

12. エンドポイントの設計

13. エンドポイントって？
http://api.example.com/users
APIにアクセスするためのURI
エンドポイント ＝ ユーザが一番見る情報
→ 覚えやすくどんな機能を持つURIなのか
ひと目でわかるものに

14. エンドポイント設計時の6箇条
1. 短く入力しやすいURI
2. 人間が読んでも理解できるURI
3. 大文字小文字が混在していないURI
4. HackableなURI
5. サーバ側のアーキテクチャによらないURI
6. ルールが統一されたURI

15. HackableなURIを目指す
• Hackable ＝ ハックしやすい
– 修正することで別のURIにするのが容易なもの
http://api.example.com/v1/items/1234
アイテム アイテムID

16. サーバの構造は関係ない！
http://api.example.com/v1/items.php
http://api.example.com/v1/cgi-bin/items.php

17. ルールは統一しよう
http://api.example.com/v1/items
http://api.example.com/v1/item?id=12
http://api.example.com/v1/items/12?status=1
複数形が混ざっていたり、URLのパスが統一されてないものは、
ユーザが混乱してしまう

18. 細かい注意点
• 単語の注意点
– 複数形の名詞にする
– 利用する英語に気をつける
– エンコード文字列は使わない
– 単語のつなぎはハイフン

19. メソッド
• GET
– 基本的にサーバのリソースを変更させない
• POST
– 新しいリソースの送信（新規登録）
• PUT
– URIで指定し、リソースを全更新
• DELETE
– 削除
• PATCH
– 指定した一部のリソースのみ更新

20. レスポンスデータの設計

21. レスポンス設計時の注意点
• ChattyなAPIを作らない
• データはフラットのほうがいいのか
• 配列で返すかオブジェクトで返すか
• レスポンスのケース
• エラーレスポンス

22. ChattyなAPI：
何度もアクセスしないと必要なデータが揃わないAPI
APIユーザ
面倒くさいAPIになる
ChattyなAPIは作らない

23. データはフラットなほうがいい？
{
"id":1,
"name":"Yuto",
"birthday":3,
"gender":"male"
}
{
"id":1,
"name":"Yuto",
"profile":{
"birthday":3,
"gender":"male"
}
}
フラットにして無駄に階層が増えてしまっている。
答え：なるべくフラットがいい
{
"id":123,
"date":"2014-12-02",
"sender":{
"id":3,
"gender":"male"
},
"receiver":{
"id":10,
"gender":"female"
}
}
階層が見やすい場合、OK

24. 配列？フォーマット？
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]
{“friends”:
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]
}
OR
以下の３つの理由から２を推奨
• レスポンスデータが何を示しているかすぐわかる
• データをオブジェクトに統一できる
• セキュリティ上のリスクを避ける事ができる
 JSONインジェクション
１、
２、

25. レスポンスの変数名
• わかりやすく、かつ短い名前に
例）userRegistrationDateTime→registeredAt
• ケースは利用しやすいほうで
 Googleはキャメルと言っているが、
Twitterなどスネークの企業も多くある
 キャメルかスネークか統一すること
• 慣習的でない省略は禁止
{“id”:1,”registeredAt”:”2015-5-5”}

26. エラーレスポンス
• ステータスコードは正しいものを返す
– 登録失敗しているのに、200とかを返さない
• エラー内容をクライアントに返す
– ヘッダに入れるかボディにいれるかは好み

27. まとめ
• どんなユーザが使うかを決める
• その上でユーザが使いやすいものを想像し、
APIを設計
• 設計におけるルール
– 基本的には慣習に乗っ取る
– 慣習が使いづらいものであれば、そこは直す

28. 参考にした本
水野 貴明 著
2014年11月 発行
by apigee
free