RESTful API
RESTful APIとは
文字通りに言いますと、RESTフルなAPIとなります。
RESTとは、REpresentational State Transferの略で、Webアーキテクチャの考え方です。
リソース指向アーキテクチャ(Resource Oriented Architecture)の考え方に沿ったものになります。
特徴は次の通りです。
リソース指向であり、一意である
getUser、deleteUserなどではなくuserという一意のリソースで定義する。
何に対して処理をするのかが明確になる。状態を管理しない
サーバーとクライアントの間で動的で余計な共有情報がなくなるため、スケーラビリティが向上する。別の情報や状態へのリンクを含む事ができる
容易に遷移できる。情報の操作（CRUD）方法があらかじめ定義されている
リクエストに統一性が生まれ、複数のサービスの組み合わせも容易になる。
どんな処理をするのかが明確になる。
RESTful APIとは、上記を満たすようなAPIとなります。
RESTful APIを設計する
RESTを満たすようなAPIを設計する手順を考えます。
リソースを明確にする
まずは下記を明確にします。
- 必要な情報 = リソースは何か
- リソースに対する操作
- リソースの親子関係（記事に対するコメントなど）
リソースはテーブルデータそのままとは限りません。
関連する情報を網羅させることも可能です。
URLを設計する
APIであることがわかるURLにする
2つの方法が一般的です。
ディレクトリに分ける方法 (https://xxx.com/api)
サブドメインを用いる方法 (https://api.xxx.com)
URLからapiのバージョンがわかるようにする
https://api.xxx.com/v1
URLには動詞を含めず、名詞は複数形で表現する
動詞(操作)はHTTPメソッドで表現します。
https://api.xxx.com/v1/items/21
itemsで切った場合はitesの一覧を表現しているとわかりますし、
21が書かれていれば、itemsの中からidが21のものを表しているとわかるため、
単数形で表現するよりも記述をシンプルにできます。
リソースの従属関係をわかりやすく表現する
https://api.xxx.com/v1/items/21/comments
idが21のitemに対するコメントである事が一目でわかります。
URLが長くならないよう、気をつける
HTTPメソッドを決定する
Web APIでは、HTTPメソッドのうち、POST、GET、PUT、DELETEの4つを使用します。
IDが変わるPOST以外は、何度操作しても結果が変わらない冪（べき）等の性質を持っています。
POST
Createのこと。GET
Readのこと。PUT
CreateまたはUpdateのこと。
Createは、IDを事前に指定できる場合にPOSTと使い分ける。DELETE
Deleteのこと。
シンプルにわかりやすく設計することで、メンテナンス性が上がり、スケーラブルなAPIになります。
参考
