Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
APIの設計ってどうやるの?
鈴木 雄登
APIの種類
• よく使われるAPIの利用目的
– 公開しているWebサービスへのアクセス用API
– 他のページに貼り付けるウィジェット
– AJAXを駆使したページ用のAPI
– スマホアプリ用のAPI
– ソシャゲ用のAPI
– 社内システムとの連携A...
こんなサービスも
Programmable Web
こんなサービスも
Programmable Web
でもAPIの設計って
あんまり解説してない
アジェンダ
• APIの設計を始める前に
• エンドポイントの設計
• レスポンスデータの設計
APIの設計を始める前に
設計に入る前に決めるべきこと
• 何をAPIで公開するのか?
– 全データのAPIを作るのか?
– 全てのAPIを作るのは、時間がかかるが、ユーザ
も増え思いがけないメリットも見つかる
• 誰を対象にしたAPIか?
– ユーザを想定しなければ、...
設計に入る前に決めるべきこと
• 何をAPIで公開するのか?
– 全データのAPIを作るのか?
– 全てのAPIを作るのは、時間がかかるが、ユーザ
も増え思いがけないメリットも見つかる
• 誰を対象にしたAPIか?
– ユーザを想定しなければ、...
アプリケーションを作るのと同じで、
誰に向けた設計かを意識するだけで、
使いやすさは全然変わってくる
エンドポイントの設計
エンドポイントって?
http://api.example.com/users
APIにアクセスするためのURI
エンドポイント = ユーザが一番見る情報
→ 覚えやすくどんな機能を持つURIなのか
ひと目でわかるものに
エンドポイント設計時の6箇条
1. 短く入力しやすいURI
2. 人間が読んでも理解できるURI
3. 大文字小文字が混在していないURI
4. HackableなURI
5. サーバ側のアーキテクチャによらないURI
6. ルールが統一された...
HackableなURIを目指す
• Hackable = ハックしやすい
– 修正することで別のURIにするのが容易なもの
http://api.example.com/v1/items/1234
アイテム アイテムID
サーバの構造は関係ない!
http://api.example.com/v1/items.php
http://api.example.com/v1/cgi-bin/items.php
ルールは統一しよう
http://api.example.com/v1/items
http://api.example.com/v1/item?id=12
http://api.example.com/v1/items/12?status=1...
細かい注意点
• 単語の注意点
– 複数形の名詞にする
– 利用する英語に気をつける
– エンコード文字列は使わない
– 単語のつなぎはハイフン
メソッド
• GET
– 基本的にサーバのリソースを変更させない
• POST
– 新しいリソースの送信(新規登録)
• PUT
– URIで指定し、リソースを全更新
• DELETE
– 削除
• PATCH
– 指定した一部のリソースのみ更新
レスポンスデータの設計
レスポンス設計時の注意点
• ChattyなAPIを作らない
• データはフラットのほうがいいのか
• 配列で返すかオブジェクトで返すか
• レスポンスのケース
• エラーレスポンス
ChattyなAPI:
何度もアクセスしないと必要なデータが揃わないAPI
APIユーザ
面倒くさいAPIになる
ChattyなAPIは作らない
データはフラットなほうがいい?
{
"id":1,
"name":"Yuto",
"birthday":3,
"gender":"male"
}
{
"id":1,
"name":"Yuto",
"profile":{
"birthday":3...
配列?フォーマット?
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]
{“friends”:
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]...
レスポンスの変数名
• わかりやすく、かつ短い名前に
例)userRegistrationDateTime→registeredAt
• ケースは利用しやすいほうで
 Googleはキャメルと言っているが、
Twitterなどスネークの企業も...
エラーレスポンス
• ステータスコードは正しいものを返す
– 登録失敗しているのに、200とかを返さない
• エラー内容をクライアントに返す
– ヘッダに入れるかボディにいれるかは好み
まとめ
• どんなユーザが使うかを決める
• その上でユーザが使いやすいものを想像し、
APIを設計
• 設計におけるルール
– 基本的には慣習に乗っ取る
– 慣習が使いづらいものであれば、そこは直す
参考にした本
水野 貴明 著
2014年11月 発行
by apigee
free
Upcoming SlideShare
Loading in …5
×

Api設計

3,590 views

Published on

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

Published in: Engineering
  • Be the first to comment

Api設計

  1. 1. APIの設計ってどうやるの? 鈴木 雄登
  2. 2. APIの種類
  3. 3. • よく使われるAPIの利用目的 – 公開しているWebサービスへのアクセス用API – 他のページに貼り付けるウィジェット – AJAXを駆使したページ用のAPI – スマホアプリ用のAPI – ソシャゲ用のAPI – 社内システムとの連携API
  4. 4. こんなサービスも Programmable Web
  5. 5. こんなサービスも Programmable Web
  6. 6. でもAPIの設計って あんまり解説してない
  7. 7. アジェンダ • APIの設計を始める前に • エンドポイントの設計 • レスポンスデータの設計
  8. 8. APIの設計を始める前に
  9. 9. 設計に入る前に決めるべきこと • 何をAPIで公開するのか? – 全データのAPIを作るのか? – 全てのAPIを作るのは、時間がかかるが、ユーザ も増え思いがけないメリットも見つかる • 誰を対象にしたAPIか? – ユーザを想定しなければ、使いやすいAPIというも のは作れない
  10. 10. 設計に入る前に決めるべきこと • 何をAPIで公開するのか? – 全データのAPIを作るのか? – 全てのAPIを作るのは、時間がかかるが、ユーザ も増え思いがけないメリットも見つかる • 誰を対象にしたAPIか? – ユーザを想定しなければ、使いやすいAPIというも のは作れない
  11. 11. アプリケーションを作るのと同じで、 誰に向けた設計かを意識するだけで、 使いやすさは全然変わってくる
  12. 12. エンドポイントの設計
  13. 13. エンドポイントって? http://api.example.com/users APIにアクセスするためのURI エンドポイント = ユーザが一番見る情報 → 覚えやすくどんな機能を持つURIなのか ひと目でわかるものに
  14. 14. エンドポイント設計時の6箇条 1. 短く入力しやすいURI 2. 人間が読んでも理解できるURI 3. 大文字小文字が混在していないURI 4. HackableなURI 5. サーバ側のアーキテクチャによらないURI 6. ルールが統一されたURI
  15. 15. HackableなURIを目指す • Hackable = ハックしやすい – 修正することで別のURIにするのが容易なもの http://api.example.com/v1/items/1234 アイテム アイテムID
  16. 16. サーバの構造は関係ない! http://api.example.com/v1/items.php http://api.example.com/v1/cgi-bin/items.php
  17. 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. 18. 細かい注意点 • 単語の注意点 – 複数形の名詞にする – 利用する英語に気をつける – エンコード文字列は使わない – 単語のつなぎはハイフン
  19. 19. メソッド • GET – 基本的にサーバのリソースを変更させない • POST – 新しいリソースの送信(新規登録) • PUT – URIで指定し、リソースを全更新 • DELETE – 削除 • PATCH – 指定した一部のリソースのみ更新
  20. 20. レスポンスデータの設計
  21. 21. レスポンス設計時の注意点 • ChattyなAPIを作らない • データはフラットのほうがいいのか • 配列で返すかオブジェクトで返すか • レスポンスのケース • エラーレスポンス
  22. 22. ChattyなAPI: 何度もアクセスしないと必要なデータが揃わないAPI APIユーザ 面倒くさいAPIになる ChattyなAPIは作らない
  23. 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. 24. 配列?フォーマット? [{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}] {“friends”: [{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}] } OR 以下の3つの理由から2を推奨 • レスポンスデータが何を示しているかすぐわかる • データをオブジェクトに統一できる • セキュリティ上のリスクを避ける事ができる  JSONインジェクション 1、 2、
  25. 25. レスポンスの変数名 • わかりやすく、かつ短い名前に 例)userRegistrationDateTime→registeredAt • ケースは利用しやすいほうで  Googleはキャメルと言っているが、 Twitterなどスネークの企業も多くある  キャメルかスネークか統一すること • 慣習的でない省略は禁止 {“id”:1,”registeredAt”:”2015-5-5”}
  26. 26. エラーレスポンス • ステータスコードは正しいものを返す – 登録失敗しているのに、200とかを返さない • エラー内容をクライアントに返す – ヘッダに入れるかボディにいれるかは好み
  27. 27. まとめ • どんなユーザが使うかを決める • その上でユーザが使いやすいものを想像し、 APIを設計 • 設計におけるルール – 基本的には慣習に乗っ取る – 慣習が使いづらいものであれば、そこは直す
  28. 28. 参考にした本 水野 貴明 著 2014年11月 発行 by apigee free

×