![配列？フォーマット？
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]
{“friends”:
[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]
}
OR
以下の３つの理由から２を推奨
• レスポンスデータが何を示しているかすぐわかる
• データをオブジェクトに統一できる
• セキュリティ上のリスクを避ける事ができる
JSONインジェクション
１、
２、](https://image.slidesharecdn.com/api-150107045342-conversion-gate01/85/Api-24-320.jpg)
Api設計
- 2. APIの種類
- 3. • よく使われるAPIの利用目的 – 公開しているWebサービスへのアクセス用API – 他のページに貼り付けるウィジェット – AJAXを駆使したページ用のAPI – スマホアプリ用のAPI – ソシャゲ用のAPI – 社内システムとの連携API
- 7. アジェンダ • APIの設計を始める前に • エンドポイントの設計 • レスポンスデータの設計
- 8. APIの設計を始める前に
- 9. 設計に入る前に決めるべきこと • 何をAPIで公開するのか？ – 全データのAPIを作るのか？ – 全てのAPIを作るのは、時間がかかるが、ユーザ も増え思いがけないメリットも見つかる • 誰を対象にしたAPIか？ – ユーザを想定しなければ、使いやすいAPIというも のは作れない
- 10. 設計に入る前に決めるべきこと • 何をAPIで公開するのか？ – 全データのAPIを作るのか？ – 全てのAPIを作るのは、時間がかかるが、ユーザ も増え思いがけないメリットも見つかる • 誰を対象にしたAPIか？ – ユーザを想定しなければ、使いやすいAPIというも のは作れない
- 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
- 18. 細かい注意点 • 単語の注意点 – 複数形の名詞にする – 利用する英語に気をつける – エンコード文字列は使わない – 単語のつなぎはハイフン
- 19. メソッド • GET – 基本的にサーバのリソースを変更させない • POST – 新しいリソースの送信（新規登録） • PUT – URIで指定し、リソースを全更新 • DELETE – 削除 • PATCH – 指定した一部のリソースのみ更新
- 20. レスポンスデータの設計
- 21. レスポンス設計時の注意点 • ChattyなAPIを作らない • データはフラットのほうがいいのか • 配列で返すかオブジェクトで返すか • レスポンスのケース • エラーレスポンス
- 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