WEB Apiの話 (Restful)

いろいろなAPIの種類

API 名	プロトコル	データの形式	通信
REST	REST	JSON、XML	同期
SOAP	SOAP	XML	同期
Streaming	Bayeux	JSON	非同期
XML-RPC	RPC	XML	同期
JSON-RPC	RPC	JSON	非同期

Twitter streaming api
cybozudev api

Restとは

• RESTはREpresentational State Transferの略。
• RESTの原則に従って実装されているシステムのことを、RESTfulと呼ぶ。
• RESTの世界では、ネットワーク上のコンテンツ(リソース)を一意なURLで表すのが基本。
• 各リソース（URL）に対してPOST、GET、PUT、DELETEでリクエストを送信する。
• 上のリクエストは、CRUD（Create、Read、Update、Delete）に紐付ける。
• 大体、レスポンスをXMLやjsonの形式で受け取る。

Restの設計

• URL設計
  • リソースを名詞であらわす。例: /user/10 /song/5 video/7
  • POST は create, GET は read, PUT は update, DELETE は delete。HTTPのメソッドをリソースの操作する。
  • リソースを名詞で表現できない場合、動詞使う。例: /search /convert
  • リクエストのパラメータを活用し、URLの階層を浅く保つこと。
  • リソースの関係の階層の表現。例: user/999/friends
• version設計
  • バージョンをつけること。(API改修は必ずある)　例:/v1/user
  • バージョンは URL にいれると, HTTP ヘッダにいれると、2 パターンがある。 　ブラウザ開発しやすいのは、URLにいれるほう。
• エラーハンドリング
  • 成功: 200, 201
  • client error: 400, 401, 403, 404
  • server error: 500
  • 変更なし: 304
• パラメータの表現
  • パラメータにカンマ区切りで指定　例: /shop?fields=name,category,location
  • offse 番目から limit 件取得　　　　例: /shop?limit=25&offset=10`

RestのDOCの便利ツール

iodocs
Swagger
Apiary.io