はじめに
Webアプリケーションを作成するうえでRESTfulAPIについて理解することは必須となります。RESTfulAPIを用いるうえでいくつか理解しておくべき内容が存在しています。しかし、現実には多くの原則が守られることなく使用されています。
今回は、備忘録的にRESTfulAPIの基礎となる内容をまとめました。
RESTfulAPIの原則
RESTfulAPIは以下の4原則で成り立っています。
- アドレス可能性 (Addressability):
- すべての情報は一のURIで識別できること
- 例:https://api.example.com/user/123 はユーザIDが123という特定のリソース
- 統一インターフェース (Uniform Interface):
- リソース操作は、標準的なHTTPメソッド(GET, POST, PUT, DELETEなど)を用いて行うこと
- データ形式(JSON,XNLなど)も一貫していることが望ましい
- ステートレス性 (Stateless):
- リクエストには必要な情報をすべて含み、過去のリクエストに関する情報は保持しないこと
- ログインなどセッションの継続性が必要な時はトークンなどを用いる
- 接続性(Connectability):
- リソースには関連する情報へリンクする情報を含めること
- 例:発注データを取得した際に商品IDなどをリンクできる情報を含める
RESTfulAPIの設計・運用
RESTful APIを設計・運用する上で一般的に必要となるいくつかの要素があります。
リソース定義とURI設計
APIが提供するデータや機能をリソースとして明確に定義します。また、そのリソースに対して直感的で一貫性のあるURIを定義します。
例)
発注データリソース … /orders (/orders/${id}も想定)
ユーザ情報リソース … /users (/users/${id}も想定)HTTPメソッド
HTTPメソッドには、GET、POST、PUT、PATCH、DELETEの5つがあり、リソースの操作に応じて適切に使用する必要があります。メソッドを正しく使用することで操作の明確化、URIの肥大化を防ぐことができます。
以下に、HTTPメソッドの概要をまとめます。
| メソッド | 概要 | データの送信方法 | URI例 |
| GET | リソースの取得 | クエリパラメータ | /users?id=123 |
| POST | リソースの作成 | リクエストボディ | /users |
| PUT | リソース更新 | リクエストボディ | /users/123 |
| PATCH | リソースの部分的な更新 | リクエストボディ | /users/123 |
| DELETE | リソースの削除 | パスパラメータ | /users/123 |
データ形式
クライアントとサーバ間でやり取りするデータ形式を標準化します。一般的にはリクエストボディを用いてJSONやXMLを用いて行われることが非常に多いです。
JSONのデータ例
{
id: 123,
loginId: 'test_user',
name: 'テストユーザ',
role: 12,
}XMLのデータ例
<?xml version="1.0" encoding="UTF-8" ?>
<user>
<id>123</id>
<loginId>test_user</loginId>
<name>テストユーザ</name>
<role>12</role>
</user>
また、リソースの作成・更新のために使用するデータはパスパラメータやクエリパラメータで送信するのは推奨されません。これらはIDの指定や更新方式などの指定に使用します。
ステータスコード
レスポンスには、処理結果としてHTTPステータスコードを付与します。HTTPステータスコードには標準のものがありますので、処理結果に応じてステータスコードの返却をします。
一般的に使用されるステータスコードの一部を以下にまとめてみました。
| ステータスコード | 意味 |
| 200 | リクエスト成功 |
| 201 | リソース作成成功(POSTやPUTで用いる) |
| 400 | クライアント側エラー(不正な構文など) |
| 403 | アクセス権限なし |
| 500 | サーバ側エラー |
クライアント側では、これらのステータスコードより成功やエラーを検出します。エラーが発生した場合にはエラーハンドリングを実施してエラーを明確に処理します。必要があれば使用者にエラーを表示して解決を促すことも大切です。
ドキュメンテーション
開発者に向けてAPIを正しく使用できるようにドキュメントを作成します。仕様がわかればどのような形式でも構いませんが、Swaggerなどを用いることでドキュメント更新を省力化することが可能です。また、レスポンス例や実際にAPIを使用する機能がありますので開発時の省力化にも役立ちます。
バージョン管理
バージョン管理することにより、APIの仕様変更時に既存のクライアントソフトを使用するユーザへの影響を最小限に抑えることができます。APIによってできることが変わってきますので、切り替え時のユーザへのアナウンス方法をはじめから考えておくとよいです。
例)
/api/v1/users
/api/v2/usersさいごに
今回はRESTfulAPIの基礎的な内容をまとめてみました。公に仕様がしっかりと考えられていますのでこれらに準拠することで開発時の標準化を行うことができます。最終的には、開発の生産性向上や品質向上につながると考えています。
なんとなくリクエスト・レスポンスは使われがちなので一度初心に戻って学習しなおすのも良い選択だと思います。
コメント