REST API設計時に気を付ける主なポイント
当ページのリンクには広告が含まれています。
✓目次
この記事の対象者
・ REST APIについてなんとなく理解している(GET, POST等のメソッドやステータスコードの使い分け等)が、設計→仕様書作成に踏み込めていない人
APIの設計
APIの設計は、大きく「リクエスト」と「レスポンス」に分けて考えられます。
APIの設計は、○○が最も望ましい！というようなものは存在しません。
企業だったり提供しているサービスによって考え方はまちまちなのかなと思います。
その中でも、API設計時に、特に意識したほうが良い点をピックアップして整理したいと思います。
以降は、「リクエスト」と「レスポンス」に分けて、要点を絞って、API設計時の考慮ポイントを整理します。
リクエスト
リクエストの設計時に考慮することは主に以下の3点があります。
・ HTTPメソッド
・ クエリパラメータとパスパラメータの使い分け
URIの設計
そもそもURIとは何を表すものなのかというと、「リソース」を表現するものです。
リソースとは、基本的には名前が付けられているものはすべてリソースになります。
例えば、サーバー側に保持されているデータもリソースです。そのほかにも、ドキュメント、サービス、商品、状態・・・これらすべて「リソース」です。よく見かけるものとしては、latestというのがあると思います。これは「latest(最新)」という「状態」を表すリソースです。
一方、リソースとしないものとして、これも所説ありますが、「動詞」は含まないことが多いです。
こういった前提を踏まえて、URI設計時に気を付ける主なポイントを以下にまとめます。
・ ②サーバー側の構造が見えないようにする
・ ③ルールが統一化されている
①誰もが読んで意味が理解できる
例えば、
http://example.com/r/u
みたいに、rとかuみたいな何らかの単語が省略されたようなURIになっているのは、あまりよくありません。
http://example.com/resources
みたいに省略せずに記載し、誤認識を防ぐような書き方をすべきと考えます。
また
http://example.com/リソース
という風なのも基本的にはNGです。
理由は、「リソース」というような2バイト文字を用いると、エンコードが必要となり、URLとしては、
http://example.com/%E3%83%AA%E3%82%BD%E3%83%BC%E3%82%B9
となってしまい、意味が理解できなくなってしまうためです。
この点も気をつけましょう。
②サーバー側の構造が見えないようにする
例えば、
http://example.com/resources.php?id=abcde
というURLとすると、サーバーサイドでPHPが用いられているのではないか、と予測できてしまいます。
これにより、悪意のある人間が脆弱性を狙い、情報漏洩等のインシデントにつながる可能性があります。
なるべくサーバーサイドの情報や仕組みをURLには反映しないように気をつけましょう。
③ルールが統一化されている
例えばあるAPIではクエリパラメータを使用し、他のAPIではパスパラメータを活用していたりすると、ルールが統一化されておらず、APIを利用する人にとってフレンドリーではなく間違いが発生します。
具体的には、顧客情報の取得として
GET http://example.com/customers?id=1234567
という風にクエリパラメータを使用しているのに対し、顧客情報の登録では、
POST http://example.com/customers/1234123
という風にパスパラメータで指定しているケースです。
この場合は、例えば両方ともパスパラメータを活用するように、統一化するのが望ましいと思います。
HTTPメソッド
以下の4つを最低限抑えておけば良いと思います。
- GET → 通常のアクセス、ページ表示、情報などのリソース取得
- POST → データ送信、新規登録、等リソースの新規登録
- PATCH/PUT → データの更新等、リソースの更新
- DELETE → データの削除等、リソースの削除
PATCHとPUTの違いは以下です。
- PATCHは、データが既に存在しているものにたいして更新をかける処理
- PUTは、データが存在しているかどうかわからないときに使い、データが存在しているときは更新をし、データが存在していないときは新規作成を行う処理になります。
設計したURLに対して、これらのメソッドを適用することで、そのリソース自体に対する操作を切り替えることができます。
クエリパラメータとパスパラメータの使い分け
リソースを一意に表す必要がある場合：パスパラメータを使用
例えばユーザIDとかがそれにあたります。
リソースを一意に表す必要がなく複数パタンが考えられる場合:クエリパラメータを使用
例えば検索条件を指定する場合、検索条件は複数パタンが考えられるのでパスには含めずにクエリパラメータを使用します。
以下に記事に分かりやすくまとめられておりますので、気になる方は参照いただければと思います。
[RESTful API]パスパラメータ、クエリパラメータ、リクエストボディの違いと設計 - Qiita
レスポンス
リクエストの設計時に考慮することは主に以下の2点があります。
・ データフォーマット
この他、データの内部構造や、エラー表現など細かい点で気を付けたほうが良いことはありますが、まずは大枠としてこの2点のみ整理したいと思います。
HTTPメソッドとステータスコード
ステータスコードは、HTTPリクエストを行った後、受け取るレスポンスの最初の行に記載されている3桁の数字です。これにより処理結果の概要を把握することができます。
100番台から500番台まで存在しますが、基本的には100番台はそこまで使用せず、200番台から500番台までを使います。
詳細な意味はその都度検索して把握すれば良いと思いますが、大まかな意味としては以下の通りとなります。
- 200番台：成功
- 300番台：リダイレクト
- 400番台：クライアントサイドに起因するエラー
- 500番台：サーバーサイドに起因するエラー
ステータスコードとメソッドの対応関係は、基本的には、以下の表にまとめている通りとなります。
| ステータスコード | GET | POST | PUT | DELETE |
|---|---|---|---|---|
| 200 OK | 〇 | 〇 登録データあり |
〇 データあり |
〇 |
| 201 Created | 〇 データなし |
〇 新規作成データなし |
||
| 202 Accepted | 〇 | 〇 | 〇 | |
| 204 No Content | 〇 更新データなし |
〇 | ||
| 304 Not Modified | 〇 キャッシュ |
|||
| 400 Bad Request | 〇 | 〇 | 〇 | 〇 |
| 401 Unauthorized | 〇 | 〇 | 〇 | 〇 |
| 403 Forbidden | 〇 | 〇 | 〇 | 〇 |
| 404 Not Found | 〇 | 〇 | 〇 | |
| 409 Conflict | 〇 データ重複など |
〇 ロックなど |
||
| 429 Too Many Requests | 〇 | 〇 | 〇 | 〇 |
| 500 Internal Server Error | 〇 | 〇 | 〇 | 〇 |
| 503 Service Unavailable | 〇 | 〇 | 〇 | 〇 |
データフォーマット
主要なレスポンスフォーマットは2種類で、XMLかJSONになります。
しかし、XMLにくらべてデータ量を減らせるJSONが主流なのではと思います。
XMLのタグは末尾にも同じ文字が必要なため冗長な記述であり、JSONと比較してデータ量が多くなってしまいます。
REST APIの設計を詳しく学びSwaggerを用いてAPI設計をしたい方は以下がおすすめ
Udemyが提供しているREST WebAPI サービス 設計という講義が参考になります。Swaggerで本格的なAPI設計のベストプラクティスを学びましょう。
