RESTAPIとは

RESTful API(REST API)とは、Webシステムを外部から利用するためのプログラムの呼び出し規約(API)の種類の一つで、RESTと呼ばれる設計原則に従って策定されたもの。RESTそのものは適用範囲の広い抽象的なモデルだが、一般的にはRESTの考え方をWeb APIに適用したものをRESTful APIと呼んでいる。

RESTful APIでは、URL/URIですべてのリソースを一意に識別し、セッション管理や状態管理などを行わない(ステートレス)。同じURLに対する呼び出しには常に同じ結果が返されることが期待される。

また、リソースの操作はHTTPメソッドによって指定(取得ならGETメソッド、書き込みならPOSTメソッド)され、結果はXMLやHTML、JSONなどで返される。また、処理結果はHTTPステータスコードで通知するという原則が含まれることもある。

引用：IT用語辞典 e-Words

RESTの設計原則

■RESTの4つの設計原則

セッションなどの状態管理を行わない。(やり取りされる情報はそれ自体で完結して解釈することができる(ステートレス))
情報を操作する命令の体系、インターフェースが予め定義・共有されている。（HTTPのGETやPOSTメソッドなど）
すべての情報は汎用的な構文で一意に識別される。（URLやURIなど）
情報の内部に、別の情報や(その情報の別の)状態へのリンクを含めることができる。（HTTPステータスなど）

リソースに対してURLが対応づけられる。（そのため、URLが名詞的になることが多い）

RESTfulについてよくわからない方はこの記事の RESTなAPIとそうではないAPIの例を参照にしてください
0からREST APIについて調べてみた

これらの原則に則ったWebサービスをRESTfulなサービスといいます。
それぞれについてもう少し説明していきます。

メリット/デメリット

メリット

アプリケーションの中のリソースがURIで示せる。

アドレス欄に入力すれば、そのリソースを参照できる。どのリソースを操作しているのか明確

URIに規則が生まれることで、利用する開発者が楽になる
ステートレスにすることで、スケーラビリティが向上

アクセスの集中に耐えやすい構造にできる

統合の相対的な容易さ

標準的なデータフォーマット(XMLやJSON)を扱うことで、他システムとの連携が容易になる
RESTに基づいたWebアプリでは、インタフェースが固定されている為互換性の問題が発生しない

デメリット

設定するREST設計をしやすいAPIフレームワークを選定する必要性。APIフレームワークの選定がREST設計に合っていないとURIの設定・変更難しくなり、コードが汚くなりうる

URI設計について

// 悪い例
https://~~~/api/getUsers/nakamura
// 良い例
https://~~~/api/users/nakamura

RESTでは一つのリソースに対してアドレス指定可能なURIが用意されていることが推奨されています。
URI設計はリソースに対してディレクトリ構成模すとシンプルかつ直感的にサービスの指定が行えます。
URIはあくまでもリソースを示すべきなので名詞のみで構成されることが原則です。/api/getUsersではなく/api/usersとします。

インターフェースの統一

RESTで用いられるHTTPメソッドは下記のようにCRUD操作と対応付けられます。

処理	HTTPメソッド	CRUD操作
登録	POST	CREATE
取得	GET	READ
更新	PUT	UPDATE
削除	DELETE	DELETE

RESTではURIで表されたリソースに対して各HTTPメソッドで操作を行います。
以下のようなURI設計が一般的です。

登録 POST    /users/userId/events
取得 GET     /users/userId/events/eventId
更新 PUT     /users/userId/events/eventId
削除 DELETE  /users/userId/events/eventId

登録処理はInsert処理であるためIDの設定をする必要がありません。
取得、更新、削除はレコード指定してCRUD操作を行う必要があるためIDをURIに付与します。

HTTPステータスコード

REST APIではリソースへのアクセス結果をHTTPステータスコードとして返します。クライアント側は、HTTPステータスコードを基に処理のハンドリングを行います。

以下に代表的なものをいくつか記載しておきます。

コード	メッセージ	説明
200	OK	成功
201	Created	作成成功（POST）
204	No Content	成功だが、返すリソースはなし
400	Bad Request	汎用エラー
401	Unauthorized	認証エラー
403	Forbidden	権限エラー
404	Not Found	該当リソース無し
405	Method Not Allowed	メソッド未対応
409	Conflict	リソースなどの衝突（作成時など）
500	Internal Server Error	サーバーエラー

参考

REST入門基礎知識
 【Spring BootでREST API】#1 イントロダクション
 0からREST APIについて調べてみた