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ステータスコードで通知するという原則が含まれることもある。
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について調べてみた