Restful API の復習


最近、サーバーレスでの開発を経験することがあり、その際Restful APIについて再度復習してみました。
翻訳: WebAPI 設計のベストプラクティス
「WebAPI 設計のベストプラクティス」に対する所感
RESTful APIのURI設計(エンドポイント設計)

Restful APIについて

 

Restful APIとは

RESTの原則に則って構築されたWebシステムのHTTPでの呼び出しインターフェースのこと。

下記記事より引用
RESTful APIとは何なのか

またRestful APIはリソース指向アーキテクチャ(ROA)の実装でもあります。
インターフェースについてはつなぎ目という意味で捉えれば良いと思います。

 

URI設計

URIを明確にする

RESTを使って、HTTPメソッドを使ったCRUDは以下のようになります。

見て分かる通り、非常に理解しやすいことがわかります。
このようにすることで、ルールも統一しやすいです。
railsとか触っていると、ここらへん最初は意識できていなかったのですが、今考えるとわかりやすいですね。(railsのせいではなく、俺が考えられていなかった…)

極力短く、人間が理解しやすくする

短いのは当然ですが、短かすぎてもわけがわからなくなります。
/fu/v のような短すぎるURIは避けるべきでしょう。

サーバ側のアーキテクチャが反映されないURI

urlにサーバー側に関する情報がわかるようにしてはいけません。
サーバー側のディレクトリ構成とか、DBのカラムなど、サーバー側のアーキテクチャがわかるようなURIは避けるべきです。

バージョンを含める

有名なAPIのURIです。
下記のような形でURIを含めています。
railsでAPIを実装した際は、/api/v2/の形で実装しました。

https://api.twitter.com/1.1/
http://qiita.com/api/v2/
http://graph.facebook.com/v2.5

エンドポイントの名前を複数形にする

この理由については、下記がわかりやすかったです。

WebAPI におけるエンドポイントはリソースを示しているからです。リソースとは API が定義する任意の事象の集合です。
任意の事象の集合とは、言葉を変えれば”概念”です。それ故何か特定の一つの事象を表すエンドポイントというものはありませんし、作るべきではありません。
超乱暴に言い換えれば「任意の数の事象が当てはまる概念」がエンドポイントですので、(複数になりうる可能性を持っている)単数と複数を包括的に複数形で表現するのが合理的です。

下記記事より引用
「WebAPI 設計のベストプラクティス」に対する所感

つまり、エンドポイントは集合を表しているので、複数形になりうる可能性を持っています。
そのため、単数と複数両方をカバーした複数形を使うことが望ましいということですね。

 

エラーメッセージの表示

エラー関連は2種類にわけることができます。
一つは、400系のクライアント起因のもの、
もう一つは、500系のサーバー起因のものがあります。

ここで気をつけなければいけないことが2つあります。
①エラーの内容に内部の情報を表現すべきではない
 これはURIの箇所で述べたことと同じです。

②wrongとかcorrectなどの主観的で抽象的な言葉は使わない
 not foundなどより具体的な表現を使えないか考えます。

 

その他メモ: べき等性について

べき等

ある操作を何回行っても、結果が同じであること

【GET, HEAD】
べき等かつ安全

【PUT, DELETE】
べき等であるが安全でない

【POST】
べき等でも安全でない