【Web API】CRUD機能のエンドポイントとリクエスト、レスポンスをどのように設計するかをざっくりまとめてみた

概要

最近APIを実装することが多かったので、忘れないようにブログにまとめます。

APIとは

APIとは、外部のプログラムからあるプログラムの機能を呼び出すための手続きを定めた規約のことです。つまり、決まりごとに過ぎないのです。APIに従ってあるプログラムの機能を呼び出す短いコードをプログラムに追加することによって、プログラム上でその機能を利用することができます。APIの詳細についてはAPIドキュメントとして公開されています。そのAPIドキュメントを見ることによって、どんな機能が提供されているのか、どんな手順でこの機能を利用できるのかが分かります。

余談ですが、「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典のAPIの説明が分かりやすかったので以下に引用します。

本当は外部のプログラムとかからその機能にお仕事を依頼するための窓口の使い方とかに関する決まり事がAPIです。
例えば「お金を入れるとケーキを作る機能」のAPIであれば
・「お金を入れるとケーキを作る機能」にお仕事を依頼するための窓口は、どこにあるの？
・窓口を使うときは無言でお金を渡せばいいの？何か一声かける必要がある？
・窓口に渡すお金は現金？小切手？カード払いはいける？
・窓口から出てきたケーキは、どうやって受け取ればいいの？お皿を用意しておく必要がある？
などの使い方ルールを含みます。
ただし、一般的には、窓口そのものと捉えた方がイメージしやすいはずです。

API (エーピーアイ)とは｜「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典

APIと実装

APIはあくまで「外部のプログラムからあるプログラムの機能を呼び出すための手続きを定めた規約」です。つまり、決まりごとに過ぎないです。呼び出される機能を実装したプログラムが存在して、初めてAPIに挙げられた機能を利用できます。

Web APIとは

Web APIとは、HTTPプロトコルを利用してネットワーク越しにプログラムを呼び出すための手続きを定めた規約のことです。ざっくり言うとWebベースのAPIです。

Web APIにおけるエンドポイントとは

Web APIにおけるエンドポイントとは、APIにアクセスするためのURIのことです。APIは通常様々な機能がセットになっているので、複数のエンドポイントを持ちます。

リソースとは

リソースとは、何らかのデータのことであり、APIであればそのエンドポイントで取得できる情報のことです。つまり、エンドポイントは、HTTPメソッドで操作する対象( = リソース)を表していると分かります。

Web APIのエンドポイント、リクエスト、レスポンス

例として、「あるユーザーに紐づくタスクに対してのCRUD機能」をAPIで提供するケースを考えます。ドメインはsample.xyzとします。

余談ですが、先ほどエンドポイントはリソースを表すと言いましたが、エンドポイントの複数形の部分は、あるデータの集合を表します。そして、エンドポイントのidなどは、個々のデータを表しています。　この決まりさえ分かれば、http://sample.xyz/api/usersにGETリクエストを出した場合、ユーザー一覧が取得できることも感覚的に理解できます。

GET

GETメソッドはリソースを取得する際に使用します。

タスク一覧機能

■ エンドポイント
http://sample.xyz/api/users/{id}/tasks

■リクエスト
- リクエストボディはなし

■レスポンス
- ステータスコードは200 OK
- レスポンスボディにユーザーに紐づくタスク一覧が格納されている
- リクエスト失敗した場合、ステータスコードは404 Not Found
- 404 Not Foundは指定したリソースが見つからないことを表す

タスク詳細機能

■ エンドポイント
http://sample.xyz/api/users/{id}/tasks/{task_id}

■リクエスト
- リクエストボディはなし

■レスポンス
- ステータスコードは200 OK
- 200 OKは、リクエストが成功したことを表す
- レスポンスボディにユーザーに紐づく指定したタスクが格納されている
- リクエスト失敗した場合、ステータスコードは404 Not Found

POST

POSTメソッドは、リソースを新規登録する際に使用します。POSTリクエストは、データの集合を表すエンドポイントに対して行います。成功すると、新しいデータがデータの集合配下に作成されます。そして、その新しいデータを表すエンドポイントでそのデータを取得できるようになります。

タスク登録機能

■エンドポイント
http://sample.xyz/api/users/{id}/tasks

■リクエスト
- リクエストボディにサーバー側に送るタスク情報が格納されている

■レスポンス
- ステータスコードは201 Created
- 201 Createdは、リクエストが成功し、新しいリソースが作成されたことを表す
- レスポンスボディには新規作成したタスクが格納されている。レスポンスボディに新規作成したタスクを格納することで、タスク登録機能を実行した後にフロント側でタスク詳細のAPIを叩かなくて済む
- リクエスト失敗した場合、ステータスコードは400 Bad Request
- 400 Bad Requestはリクエストが正しくないことを表す

PATCH

PATCHメソッドは、指定したリソースの一部分を更新する際に使用します。PUTメソッドは送信するデータで元々のリソースを完全に上書きしてしまうらしいです(未検証)。指定したリソースを更新したい場合はPATCHメソッドを使用しましょう。

タスク更新機能

■エンドポイント
http://sample.xyz/api/users/{id}/tasks/{task_id}

■リクエスト
- リクエストボディには、更新するデータが格納されている

■レスポンス
- ステータスコードは200 OK
- レスポンスボディには更新したデータが格納されている
- リクエスト失敗した場合、ステータスコードは400 Bad Requestまたは404 Not Found

DELETE

DELETEメソッドは、指定したリソースの削除をする際に使用します。エンドポイントで指定したリソースを削除します。

タスク削除機能

■エンドポイント
http://sample.xyz/api/users/{id}/tasks/{task_id}

■リクエスト
- リクエストボディはなし

■レスポンス - ステータスコードは204 No Content
- 204 No Contentは、リクエストが成功したがレスポンスボディが空であることを表します。
- 削除した後に、もう一度削除したリソースを使うというケースはあまり考えられないため、204 No Contentにしています。
- リクエスト失敗した場合、ステータスコードは404 Not Found

まとめ

「あるユーザーに紐づくタスクに対してのCRUD機能」をAPIで提供した場合、5つ機能があるのに必要なエンドポイントは2つしかないことが分かりました。エンジニアになりたての頃、5つ機能があるから5つエンドポイントが必要なのかと勘違いしていたのですが、そんなことはないのでAPI設計するときは注意しましょう。