API 設計における HTTP ステータス コードの究極のリファレンス

Web 開発と API 設計の世界では、HTTP ステータス コードは、クライアントとサーバーの間でリクエストの結果を伝達する際に重要な役割を果たします。これらのコードは、HTTP リクエストの処理中に発生する特定の条件、成功、またはエラーを示す標準化された方法を提供します。これらのステータス コードを理解することは、デバッグ、エラー処理、およびより堅牢なアプリケーションの作成に役立つため、開発者にとって不可欠です。

1. 1xx 情報

これらのステータス コードは暫定的な応答を示します。実際にはほとんど使用されませんが、特定のシナリオでは役立つことがあります。

• 100 Continue: サーバーはリクエスト ヘッダーを受信したため、クライアントはリクエスト本文の送信に進む必要があります。
• 101 プロトコルの切り替え: リクエスターはサーバーにプロトコルを切り替えるように要求し、サーバーはそれに同意しました。

2. 2xx の成功

これらのステータス コードは、クライアントのリクエストが正常に受信、理解、受け入れられたことを示します。

• 200 OK: リクエストは成功し、応答にはリクエストされたデータまたは結果が含まれています。
  • 例: ユーザーのプロフィール情報を取得します。
• 201 Created: リクエストは成功し、新しいリソースが作成されました。
  • 例: 新しいユーザー アカウントを作成するか、新しいブログ エントリを投稿します。
• 204 No Content: サーバーはリクエストを正常に処理しましたが、コンテンツを返しません。
  • 例: 応答本文が必要ないユーザーの設定を更新します。
• 206 部分コンテンツ: クライアントから送信された範囲ヘッダーのため、サーバーはリソースの一部のみを配信しています。
  • 例: ビデオ コンテンツのストリーミングまたは大きなファイルの分割ダウンロード。

3. 3xx リダイレクト

これらのステータス コードは、リクエストを満たすためにユーザー エージェントがさらにアクションを実行する必要があることを示します。

• 301 Moved Permanently: 要求されたリソースは新しい URL に永続的に移動されました。
• 302 Found: 要求されたリソースは一時的に別の URL に存在します。
• 304 Not Modified: リクエスト ヘッダーで指定されたバージョン以降、リソースが変更されていないことを示します。

4. 4xx クライアント エラー

これらのステータス コードは、クライアントがエラーを犯したと思われる状況を対象としています。

• 400 Bad Request: 無効な構文または不正な入力のため、サーバーはリクエストを処理できません。

  • 例: リクエスト本文で不正な形式の JSON を送信します。
  • 使用法: リクエスト自体の形式が不正であるか、無効なパラメーターが含まれている場合に使用します。

• 401 Unauthorized: リクエストにはユーザー認証が必要です。

  • 例: 有効な資格情報を提供せずに、保護された API エンドポイントにアクセスしようとしています。
  • 使用法: 認証が必要であるが、提供されていないか無効な場合に使用します。

• 403 Forbidden: サーバーはリクエストを理解しましたが、承認を拒否しました。

  • 例: ユーザーが管理者専用の機能にアクセスしようとしています。
  • 使用法: ユーザーが認証されているが、要求された操作に対する権限を持っていない場合に使用します。

• 404 Not Found: 要求されたリソースがサーバー上に見つかりませんでした。

  • 例: 削除されたユーザー プロファイルを取得しようとしています。
  • 使用法: 要求されたリソースが存在しない場合に使用します。

• 405 メソッドは許可されていません: リクエストで指定されたメソッドは、リクエスト URI で識別されるリソースに対して許可されていません。

  • 例: GET リクエストのみを受け入れるエンドポイントに POST リクエストを送信します。

• 409 競合: リソースの現在の状態と競合するため、リクエストを処理できませんでした。

  • 例: システムに既に存在する電子メールを使用してユーザーを作成しようとしています。
  • 使用法: 重複エントリなど、リソースの現在の状態と矛盾がある場合に使用します。

• 422 処理できないエンティティ: サーバーはリクエストのコンテンツ タイプと構文を理解していますが、含まれている命令を処理できません。

  • 예: 서버 측 검증에 실패한 잘못된 데이터가 포함된 양식 제출.
  • 용도: 요청 구문은 정확하지만 데이터가 의미상 잘못된 유효성 검사 오류에 사용됩니다.

• 429 요청이 너무 많음: 사용자가 지정된 시간 동안 너무 많은 요청을 보냈습니다("속도 제한").

  • 예: 남용 방지를 위해 API 속도 제한 구현

5. 5xx 서버 오류

이러한 상태 코드는 서버가 오류가 발생했거나 요청을 수행할 수 없음을 인식하는 경우를 나타냅니다.

• 500 내부 서버 오류: 서버가 요청을 이행하지 못하게 하는 예상치 못한 상황이 발생했음을 나타내는 일반적인 오류 메시지입니다.

  • 예: 서버측 코드에서 처리되지 않은 예외가 발생합니다.

• 501 구현되지 않음: 서버가 요청을 이행하는 데 필요한 기능을 지원하지 않습니다.

  • 예: 서버가 인식하지 못하는 새로운 HTTP 방식을 사용하는 경우

• 502 Bad Gateway: 서버가 게이트웨이 또는 프록시 역할을 하는 동안 업스트림 서버로부터 잘못된 응답을 받았습니다.

  • 예: 역방향 프록시 서버가 원본 서버에 연결할 수 없습니다.

• 503 서비스를 사용할 수 없음: 일시적인 과부하 또는 유지보수로 인해 서버가 현재 요청을 처리할 수 없습니다.

  • 예: 서버가 예정된 유지 관리를 진행 중이거나 트래픽이 많습니다.

• 504 게이트웨이 시간 초과: 서버가 게이트웨이 또는 프록시 역할을 하는 동안 업스트림 서버로부터 적시에 응답을 받지 못했습니다.

  • 예: 타사 API의 응답을 기다리는 동안 시간 초과가 발생합니다.

HTTP 상태 코드 사용에 대한 모범 사례

1. 구체적: 상황에 적용되는 가장 구체적인 상태 코드를 사용하세요. 이는 고객이 발생한 일과 대응 방법을 정확히 이해하는 데 도움이 됩니다.

2. 일관적인 사용: API 전체에서 상태 코드를 사용하는 방식에 일관성을 유지하세요. 이렇게 하면 개발자가 API 작업을 더 쉽게 할 수 있습니다.

3. 추가 정보 제공: 적절한 경우 상태 코드와 함께 응답 본문에 자세한 오류 메시지를 포함하세요. 이는 디버깅에 도움이 되며 개발자 경험을 향상시킬 수 있습니다.

4. 보안 고려 사항: 특히 4xx 및 5xx 오류의 경우 오류 응답에서 너무 많은 정보를 공개하지 않도록 주의하세요. 시스템 아키텍처 또는 구현에 대한 민감한 세부 정보를 노출하지 마세요.

5. 문서화: API가 사용하는 상태 코드와 상황을 명확하게 문서화하세요. 이는 API 소비자가 다양한 응답을 해석하고 처리하는 방법을 이해하는 데 도움이 됩니다.

HTTP 상태 코드를 이해하고 적절하게 구현함으로써 개발자는 더욱 강력하고 명확하며 사용자 친화적인 API 및 웹 애플리케이션을 만들 수 있습니다. 이러한 코드는 클라이언트와 서버 간의 중요한 통신 도구 역할을 하여 오류 처리를 간소화하고 전반적인 시스템 안정성을 향상시키는 데 도움이 됩니다.

以上がAPI 設計における HTTP ステータス コードの究極のリファレンスの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。