REST APIのステータスコード一覧と適切な使い方

新人と先輩の会話形式で理解しよう

新人

「先輩、REST APIってよく聞くんですけど、正直まだよくわかっていません。簡単に教えてもらえますか？」

先輩

「もちろん！REST APIは、Webアプリケーションがやり取りするためのルールなんだ。たとえば、データの取得・登録・更新・削除などをHTTPの仕組みを使って実現するんだよ。」

新人

「なるほど…。あと、ステータスコードって何か意味があるんですか？数字ばっかりでピンと来なくて…」

先輩

「ステータスコードは、REST APIの応答に含まれる番号で、リクエストが成功したかどうか、何か問題があったかなどを伝える大事な情報なんだ。それじゃあ、REST APIとステータスコードの基本を順番に見ていこうか！」

1. REST APIとは何か？

REST API（レスト・エーピーアイ）は、「Representational State Transfer」の略で、HTTPをベースにした通信のルールを指します。Webサービスの開発では、クライアント（フロントエンド）とサーバー（バックエンド）が情報をやりとりするために、REST APIがよく使われます。

たとえば、ユーザー情報を取得するにはGET、新しくデータを作るにはPOST、データを更新するにはPUT、削除するにはDELETEなど、HTTPのメソッドを活用して操作します。

Springアプリケーションでも、REST APIはよく使われ、Javaの@RequestMappingや@GetMappingなどを使ってAPIを実装します。今回の記事では、特に「REST APIのステータスコード」について、初心者向けにくわしく解説します。

2. ステータスコードとは何か？

ステータスコードは、HTTPレスポンスの中に含まれる3桁の数字で、リクエストの処理結果を示します。例えば「200 OK」なら成功、「404 Not Found」なら指定されたデータが見つからなかったことを意味します。

REST APIでは、このステータスコードを正しく使うことで、クライアント側がサーバーの状況を正しく把握できます。逆に間違ったコードを返すと、バグの原因になったり、ユーザーに誤解を与える可能性があります。

以下は、Springの@Controllerを使って、ステータスコードを返す簡単な例です。


@Controller
public class UserController {

    @GetMapping("/user")
    public ResponseEntity<String> getUser() {
        // 通常の処理が成功したとき
        return new ResponseEntity<>("ユーザー情報を取得しました", HttpStatus.OK);
    }

    @GetMapping("/user/error")
    public ResponseEntity<String> getUserError() {
        // ユーザーが存在しないとき
        return new ResponseEntity<>("ユーザーが見つかりません", HttpStatus.NOT_FOUND);
    }
}

このように、SpringのResponseEntityを使えば、HTTPステータスコードを簡単に指定することができます。初心者の方はまず、よく使われるステータスコードとその意味を覚えるところから始めるとよいでしょう。

次回の記事では、「REST APIでよく使われるHTTPステータスコード一覧」と「それぞれの使い方」について詳しく解説します。

3. よく使うステータスコード一覧

REST APIでは、HTTPのステータスコードを正しく使うことが非常に重要です。ここでは、実際のSpring開発でよく使われる代表的なステータスコードを紹介します。

200 OK： 正常に処理されたとき
201 Created： 新しいリソースが作成されたとき
204 No Content： 処理は成功したが返すデータがないとき
400 Bad Request： リクエストの内容に誤りがあるとき
401 Unauthorized： 認証が必要なとき、または失敗したとき
403 Forbidden： アクセス権限がないとき
404 Not Found： 指定されたリソースが存在しないとき
500 Internal Server Error： サーバー内部で予期しないエラーが起きたとき

これらは@Controllerを使用したSpringアプリケーションでも頻繁に登場する基本的なステータスコードです。初心者の方はまずこの8種類を確実に理解しましょう。

4. 各ステータスコードの意味と適切な使いどころ

それぞれのステータスコードは、特定の状況に応じて適切に使い分ける必要があります。以下では、使用例とともに詳しく解説していきます。

200 OK の使い方

最もよく使われるステータスコードです。データの取得や、通常の操作が成功した場合に使用します。


@Controller
public class ProductController {

    @GetMapping("/products")
    public ResponseEntity<String> getAllProducts() {
        return new ResponseEntity<>("全ての製品を取得しました", HttpStatus.OK);
    }
}

201 Created の使い方

POSTリクエストで新しいリソースが作成された場合に使います。作成に成功したことを明確に示せるため、APIの信頼性も向上します。


@Controller
public class ProductController {

    @PostMapping("/products")
    public ResponseEntity<String> createProduct() {
        return new ResponseEntity<>("新しい製品を作成しました", HttpStatus.CREATED);
    }
}

204 No Content の使い方

削除処理などで処理は成功したが、返すべきデータがない場合に使用します。無駄なデータ送信を避けられます。


@Controller
public class ProductController {

    @DeleteMapping("/products/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable String id) {
        // 削除処理
        return new ResponseEntity<>(HttpStatus.NO_CONTENT);
    }
}

400 Bad Request の使い方

クライアントからのリクエストに誤りがある場合に使用します。たとえば、必須パラメータが不足していたり、形式が不正なときです。


@Controller
public class ProductController {

    @GetMapping("/products/search")
    public ResponseEntity<String> search(@RequestParam(required = false) String keyword) {
        if (keyword == null || keyword.isBlank()) {
            return new ResponseEntity<>("検索キーワードが未指定です", HttpStatus.BAD_REQUEST);
        }
        return new ResponseEntity<>("検索結果を返します", HttpStatus.OK);
    }
}

401 Unauthorized の使い方

ログイン認証が必要だが認証されていない場合に使用します。例えば、ログインしていないユーザーが保護されたリソースにアクセスしようとした場合です。


@Controller
public class SecureController {

    @GetMapping("/secure/data")
    public ResponseEntity<String> getSecureData(HttpSession session) {
        if (session.getAttribute("user") == null) {
            return new ResponseEntity<>("ログインが必要です", HttpStatus.UNAUTHORIZED);
        }
        return new ResponseEntity<>("秘密のデータです", HttpStatus.OK);
    }
}

403 Forbidden の使い方

ログインしていてもアクセス権限がないユーザーが不正に操作しようとしたときに使用します。例えば、一般ユーザーが管理者用ページにアクセスしたときです。


@Controller
public class AdminController {

    @GetMapping("/admin")
    public ResponseEntity<String> accessAdmin(HttpSession session) {
        String role = (String) session.getAttribute("role");
        if (!"admin".equals(role)) {
            return new ResponseEntity<>("管理者権限が必要です", HttpStatus.FORBIDDEN);
        }
        return new ResponseEntity<>("管理者ページへようこそ", HttpStatus.OK);
    }
}

404 Not Found の使い方

指定されたリソースが存在しない場合に使います。例えば、存在しないIDのデータを取得しようとしたときなどです。


@Controller
public class ProductController {

    @GetMapping("/products/{id}")
    public ResponseEntity<String> getProduct(@PathVariable String id) {
        boolean exists = false; // 仮の存在チェック
        if (!exists) {
            return new ResponseEntity<>("指定された製品は存在しません", HttpStatus.NOT_FOUND);
        }
        return new ResponseEntity<>("製品詳細を返します", HttpStatus.OK);
    }
}

500 Internal Server Error の使い方

サーバー側の処理中に予期せぬエラーが発生したときに使用します。データベースの障害や、例外の未処理などが原因になることがあります。


@Controller
public class ProductController {

    @GetMapping("/products/error")
    public ResponseEntity<String> getError() {
        try {
            int result = 10 / 0; // 故意のエラー
        } catch (Exception e) {
            return new ResponseEntity<>("サーバー内部エラーが発生しました", HttpStatus.INTERNAL_SERVER_ERROR);
        }
        return new ResponseEntity<>("正常応答", HttpStatus.OK);
    }
}

このように、HTTPステータスコードを状況に応じて正しく返すことが、API開発では非常に重要です。@ControllerベースのSpringアプリケーションでも、ResponseEntityとHttpStatusを組み合わせることで、明確なレスポンスを実装することが可能です。

次のパートでは、初心者が間違いやすいステータスコードの使い方や注意点、そして正しく使うためのベストプラクティスについて解説していきます。

5. ステータスコードの使い方でありがちなミスとその対策

ステータスコードは単なる番号ではなく、クライアントとサーバーの意思疎通を助ける重要な要素です。しかし、初心者がよくやってしまう「間違った使い方」も少なくありません。ここでは、代表的なミスとその対策を紹介します。

200 OK を多用しすぎる

「とりあえず 200 OK を返せばよい」と思い込んで、エラー時にも 200 を返してしまうケースがあります。これではクライアントが失敗を検知できず、ユーザーに不適切なメッセージが表示されることになります。

対策：リクエストが失敗した場合は、適切な 4xx や 5xx のステータスコードを返すようにしましょう。

400 と 422 の違いがわからない

フォームバリデーションのエラーなどで「400 Bad Request」を使うべきか「422 Unprocessable Entity」を使うべきか迷う場面があります。Springでは 422 を標準で使うことは少ないですが、REST API の設計方針によっては明確に使い分けが必要です。

対策：400 はリクエスト形式自体に誤りがある場合、422 は構文は正しいが内容に問題がある場合に使い分けましょう。

401 Unauthorized と 403 Forbidden の混同

このふたつはよく混同されますが、「未認証」と「認証済みだが権限がない」では意味が全く異なります。

対策：ログインしていないユーザーには 401、ログイン済みだがアクセス権限がない場合は 403 を返すようにしましょう。

500 を乱用する

とにかくエラーが起きたら 500 を返すという実装は危険です。開発中のバグを隠すことになり、保守性が落ちます。

対策：想定されるエラーは例外処理でキャッチし、適切なステータスコードを返すように心がけましょう。

6. Spring（@Controller）で適切にステータスコードを返す方法（実装例）

Springアプリケーションでは、@ControllerとResponseEntityを使えば、HTTPステータスコードを柔軟に制御できます。ここでは、よくある3つのケースでの実装例を紹介します。

登録処理で 201 Created を返す


@Controller
public class UserController {

    @PostMapping("/users")
    public ResponseEntity<String> createUser(@RequestParam String name) {
        // 登録処理（省略）
        return new ResponseEntity<>("ユーザーを作成しました", HttpStatus.CREATED);
    }
}

パラメータが不足している場合に 400 を返す


@Controller
public class UserController {

    @GetMapping("/users/search")
    public ResponseEntity<String> searchUser(@RequestParam(required = false) String keyword) {
        if (keyword == null || keyword.isBlank()) {
            return new ResponseEntity<>("検索キーワードが指定されていません", HttpStatus.BAD_REQUEST);
        }
        return new ResponseEntity<>("検索結果を返します", HttpStatus.OK);
    }
}

ログインしていない場合に 401 を返す


@Controller
public class SecureController {

    @GetMapping("/secure/info")
    public ResponseEntity<String> getSecureInfo(HttpSession session) {
        if (session.getAttribute("user") == null) {
            return new ResponseEntity<>("認証が必要です", HttpStatus.UNAUTHORIZED);
        }
        return new ResponseEntity<>("保護された情報です", HttpStatus.OK);
    }
}

このように、@Controllerでも@RestControllerを使わなくても、ResponseEntityを活用すれば、ステータスコードの使い分けが簡単に実装できます。

7. API開発時に意識したいポイント（設計・保守性）

REST APIのステータスコードは、単なる「数字の応答」ではなく、クライアントとの「約束ごと」のようなものです。開発の際には以下の点を意識して設計・実装しましょう。

1. 意図が明確に伝わるステータスコードを選ぶ

単に動くAPIではなく、「この処理が成功したのか失敗したのか」「なぜ失敗したのか」が一目でわかるようなレスポンスを返すことが大切です。200 だけではなく、201 や 204 なども積極的に使いましょう。

2. エラー処理も仕様として設計に含める

API設計時には「成功時」のみならず、「失敗したときにどう返すか」も決めておくことで、後からの修正が少なくなります。例えば「未認証なら 401」「データがなければ 404」「処理失敗なら 500」など。

3. 保守性を高めるために一貫性を重視する

同じ種類の処理には、常に同じステータスコードを返すようにしましょう。APIが増えるにつれ、コードの一貫性が保たれていないと、クライアント側の開発者が混乱します。

4. API仕様書にステータスコードを明記する

Swaggerなどを使ってAPI仕様を管理している場合、ステータスコードとその意味・使いどころを必ずドキュメントに残しましょう。そうすることで、チーム内の認識ズレを防ぐことができます。

5. 開発中はログ出力と例外管理を丁寧に

意図しないエラーで 500 が返るような状況は極力避けるべきです。try-catch構文を使って予期せぬ例外も適切にキャッチし、必要に応じて 400 や 404 に変換して返すと、ユーザーにもやさしいAPIになります。

以上のポイントを意識することで、ステータスコードの使い分けが適切になり、クライアントからの信頼性も高まります。Spring（@Controller）で開発するREST APIでも、こうした細かな配慮が品質に直結します。

まとめ

REST APIとHTTPステータスコードの振り返り

ここまで、REST APIの基本的な考え方から、HTTPステータスコードの役割、そしてSpringの@Controllerを使った具体的な実装例までを順を追って見てきました。 REST APIは単にデータをやり取りする仕組みではなく、クライアントとサーバーが共通のルールで会話するための設計思想そのものだという点が重要です。その中でも、HTTPステータスコードは「処理結果を正しく伝えるための言葉」のような存在であり、APIの使いやすさや信頼性を大きく左右します。

例えば、データ取得が成功した場合に200 OKを返す、新しいリソースを作成した場合に201 Createdを返す、削除が成功して返却データが不要な場合に204 No Contentを返す、といった使い分けは、 REST APIを利用する側にとって非常にわかりやすい合図になります。一方で、リクエストの内容に誤りがあれば400 Bad Request、認証が必要であれば401 Unauthorized、権限不足であれば403 Forbidden、リソースが存在しなければ404 Not Foundを返すことで、クライアントは「何が原因で失敗したのか」を正確に理解できます。

また、500 Internal Server Errorはサーバー側の想定外の問題を示す重要なステータスコードですが、何でもかんでも500を返してしまうと、本来クライアント側で修正すべきミスと、サーバー側の障害とを区別できなくなってしまいます。そのため、例外処理や入力チェックを丁寧に行い、可能な限り4xx系のステータスコードとして返す設計が求められます。

Spring（@Controller）での実装ポイント

Springアプリケーションでは、@ControllerとResponseEntity、HttpStatusを組み合わせることで、 REST APIにおけるステータスコードの制御を非常に柔軟に行うことができます。 @RestControllerを使わなくても、明示的にResponseEntityを返すことで、レスポンスボディとHTTPステータスコードを同時に指定できる点は、初心者にとっても理解しやすいポイントです。

以下は、この記事で学んだ考え方を踏まえた、シンプルなまとめ用サンプルプログラムです。処理結果に応じて、適切なステータスコードを返すことで、APIの意図が明確になります。


@Controller
public class SummaryController {

    @GetMapping("/summary/sample")
    public ResponseEntity<String> sample(@RequestParam(required = false) String value) {
        if (value == null || value.isBlank()) {
            return new ResponseEntity<>("値が指定されていません", HttpStatus.BAD_REQUEST);
        }
        return new ResponseEntity<>("正常に処理されました", HttpStatus.OK);
    }
}

このように、APIの処理結果とステータスコードを常にセットで考える習慣を身につけることで、保守性が高く、他の開発者にもやさしいREST APIを設計できるようになります。ステータスコードは後付けで考えるものではなく、API設計の段階から意識することが大切です。

REST API設計で身につけたい考え方

本記事を通して理解しておきたいのは、「HTTPステータスコードは仕様の一部である」という点です。正しく設計されたREST APIでは、クライアントはレスポンスボディを細かく解析しなくても、ステータスコードを見るだけで大まかな結果を判断できます。これは、フロントエンド開発やモバイルアプリ開発、外部サービス連携など、あらゆる場面で大きなメリットになります。

SpringでREST APIを開発する際は、@Controller、@GetMapping、@PostMapping、ResponseEntity、HttpStatusといった基本要素をしっかり理解し、それぞれのステータスコードの意味と使いどころを自分の言葉で説明できるようになることを目標にしましょう。それが結果として、バグの少ないAPI設計や、チーム開発での円滑なコミュニケーションにつながります。

先生と生徒の振り返り会話

生徒

「最初はステータスコードって、ただの数字の一覧だと思っていましたけど、 REST APIではクライアントとサーバーの会話を支える大事な要素なんですね。」

先生

「その通りだね。ステータスコードを正しく使えるようになると、 APIの設計レベルが一段上がったと言ってもいいよ。」

生徒

「200や404だけじゃなくて、201や204、401と403の違いも意識しないといけない理由がよくわかりました。 SpringのResponseEntityを使えば実装も難しくないですね。」

先生

「うん。大事なのは、処理が成功したか失敗したかだけじゃなく、どういう理由でその結果になったのかを、ステータスコードで正確に伝えることだね。」

生徒

「これからは、とりあえず200を返すんじゃなくて、 APIを使う人の立場を考えてステータスコードを選ぶようにします。」

先生

「それができれば立派だよ。REST APIとHTTPステータスコードを正しく使いこなせば、読みやすくて信頼できるAPIが自然と書けるようになるから、ぜひ実践してみよう。」