REST APIの設計思想

RESTとは
- ユーザー情報を取得するAPI
- ユーザー情報に関連するデータを取得
RESTらしいAPIとは

RESTとは

Web APIについて調べると最近でもまだRESTという単語は良く聞くかと思います。
RESTというのは、Web APIを作成する上での設計モデル(アーキテクチャスタイル)です。
RESTの考えとしてはURIが対象APIリソースを表現するため、名詞で表現するのが一般的です。
「RESTfulとRESTって何が違うの？」という方もいるかもしれませんが、これについてはRESTを掲げている時点でRESTの制約に従っているという意味だと考えていいので、同意義で良いと思います。
ただ、世の中ではREST APIと謳っているものの、残念ながらそうでないWeb APIもあったりします。
早速どのような感じで設計していくのか考えて行きましょう。

ユーザー情報を取得するAPI

URI	METHOD	DISCRIPTION
example.com/v1/users/	POST	idを1とするユーザーを作成
example.com/v1/users/2	GET	idが2のユーザーを取得する
example.com/v1/users	GET	ユーザーのリスト取得を取得する
example.com/v1/users/20	DELETE	idが20のユーザーを削除する
example.com/v1/users/3	PUT	idが3のユーザーを更新する

このように各HTTPメソッドがCRUD処理を扱ってくれます。
v1というのは新旧でAPIに変更があった場合にバージョン番号としています。
バージョニングについては1.1やv1.1など数値やvを接頭につけるケースが多いですね。
しかし、これだけだと「関連データに対してのどのように振る舞うべきなの？」と思う方もおそらくいると思います。
この場合はこのようなケースで良いでしょう。

ユーザー情報に関連するデータを取得

URI	METHOD	DISCRIPTION
example.com/v1/users/4/hobbys	GET	idが4に関連するユーザーの趣味についてのデータを取得する
example.com/v1/users/10/skills	GET	idが10に関連するユーザーのスキルについてのデータを取得する

システム構成などを考えず、図で流れを書くと以下のような形ですね。

RESTらしいAPIとは

ステートレスであること（セッションなど、APIで状態管理を行わない）
URIはリソースを表現する名詞にする（名前付けは悩む事が多いと思いますが、どうしても長くなってしまうのであれば単語をハイフン(-)で繋げるのが良いと思います。）
URIは複数形にする
インターフェースを統一する（データ登録はPOST、取得はGET、削除はDELETEなど）
KISS（Keep it simple stupid）の原則に習う（簡潔でわかりやすい）

RESTのメリット

ステートレスになるため、サーバー側のシステムは複雑にならない
リソース指向のURIなので開発者は直感的に扱える
統一インターフェースなので互換性がある
外部向けとしたAPIの場合に扱ってもらいやすい
CoolなURI

RESTのデメリット

REST的に間違っている場合でも認証系では捨てざるを得ない場面がある（Cookieなどを使ったセッション管理）
送信するデータ量が多くなるため、パフォーマンスの低下が考えられる

その他

RESTとは直接関係ないですが、Web APIでもHTTPのステータスコードについては意外と気を使っているようでそうでないケースもあります。
私も過去に理解する前にWeb APIを作成した時にこの辺りは失敗してしまいました。
例えば404 Not Foundで返すべき情報を200 OKで返してしまったり、こういったケースは結構多いと思っています。
こういった実装ですと検索エンジンのロボットが勘違いして問題が生じるケースも存在します。
ステータスコードは自身で追加などは出来ないモノなので、使う言語やフレームワークに合わせて適切なモノを返すように心掛けることでより良いAPIが作成出来ると思います。