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が作成出来ると思います。