APIを設計したり、API仕様書を書いたりする時に、APIのステータスコードが決して必要な一部分になります。それでは、APIステータスコードとはなんですか？どのように設計すればいいですか？本文では、これらの点を取り上げ、みんさんに紹介します。
APIステータスコードとは？
APIステータスコードは、Web APIの応答メッセージに含まれる数値コードであり、APIの処理結果や応答の状態を示すために使用されます。クライアントがAPIを呼び出した際に、サーバーから返されるステータスコードは、クライアントに対してリクエストの成功、失敗、またはその他の特定の状態を伝える重要な情報となります。
APIのスターテスコードは、APIの特徴と機能に基づいて設定される必要があります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。
APIステータスコードの役割
APIステータスコードは、APIの応答メッセージに含まれる数値コードであり、クライアントに対してAPIの処理結果や応答の状態を伝える役割があります。以下に、APIステータスコードの主な役割を説明します:
リクエストの成功や失敗の通知
ステータスコードは、クライアントに対してリクエストの成功または失敗を伝えます。成功したリクエストには、通常は「200 OK」ステータスコードが返されます。一方、エラーや問題が発生した場合には、異なるステータスコードが返されます。
エラーの特定と処理
ステータスコードは、エラーが発生した場合にその具体的な種類や原因を示します。クライアントはステータスコードを確認することで、どのようなエラーが発生したかを特定し、適切なエラーハンドリングや処理を行うことができます。例えば、401 Unauthorizedステータスコードは認証エラーを示し、クライアントに認証を要求することを示します。
リダイレクトの通知
ステータスコードは、一部のリクエストがリダイレクションを必要とする場合に使用されます。例えば、「302 Found」ステータスコードは、リソースが一時的に別の場所に移動されていることを示し、クライアントは新しい場所にリクエストを再送信する必要があることを伝えます。
応答の詳細情報
ステータスコードは、追加のメタデータや詳細情報を含むことがあります。例えば、「403 Forbidden」ステータスコードでは、アクセスが禁止されている理由や許可される条件などの追加情報が応答に含まれることがあります。
APIステータスコードは、クライアントがAPIとの通信中に発生するさまざまな状態やエラーを理解し、適切なアクションを実行するための重要な情報源です。クライアントはステータスコードを適切に処理して、エラー回復、再試行、リダイレクトの処理などを行うことができます。
API HTTPステータスコード一覧表
以下は、一般的なAPIステータスコードを含むテーブルです。
| ステータスコード | タイプ | 説明 |
|---|---|---|
| 200 OK | 成功 | リクエストが成功し、正常なレスポンスが返されたことを示します。 |
| 201 Created | 成功 | リクエストが成功し、新しいリソースが作成されたことを示します。 |
| 204 No Content | 成功 | リクエストが成功し、レスポンスにコンテンツがないことを示します。 |
| 400 Bad Request | クライアントエラー | リクエストが不正であるため、サーバーがリクエストを解釈できないことを示します。 |
| 401 Unauthorized | 認証とセキュリティエラー | 認証が必要なリソースに対して、クライアントが認証されていないことを示します。 |
| 403 Forbidden | クライアントエラー | リクエストされたリソースへのアクセスが禁止されていることを示します。 |
| 404 Not Found | クライアントエラー | リクエストされたリソースが見つからないことを示します。 |
| 409 Conflict | クライアントエラー | リクエストが競合しているため、リソースの操作が失敗したことを示します。 |
| 422 Unprocessable Entity | 業務エラー | リクエストデータが処理できない形式であることを示し、業務規則に違反していることを伝えます。 |
| 429 Too Many Requests | 業務エラー、制限と割当量エラー | リクエストが制限や割当量を超えているため、一時的にリクエストを制限または拒否していることを示します。 |
| 451 Unavailable For Legal Reasons | 業務エラー | リクエストが法的な理由で利用できないことを示します。 |
| 500 Internal Server Error | サーバーエラー | サーバーで予期しないエラーが発生したことを示します。 |
| 502 Bad Gateway | サーバーエラー | ゲートウェイサーバーが無効なレスポンスを受信したことを示します。 |
| 503 Service Unavailable | サーバーエラー | サーバーが一時的に過負荷やメンテナンスのために利用できない状態であることを示します。 |
| 504 Gateway Timeout | サーバーエラー | ゲートウェイサーバーがタイムアウトしたことを示します。 |
| 507 Insufficient Storage | サーバーエラー | サーバーが保存領域の容量不足で要求を処理できないことを示します。 |
| 509 Bandwidth Limit Exceeded | 制限と割当量エラー | アクセス帯域幅の制限を超えたため、サーバーがアクセスを拒否していることを示します。 |
| 419 Authentication Timeout | 認証とセキュリティエラー | セッションの認証タイムアウトが発生したことを示します。 |
| 498 Invalid Token | 認証とセキュリティエラー | 提供されたトークンが無効であることを示します。 |
このテーブルは一般的なステータスコードの例を含んでいますが、APIの仕様や実装によっては、さらに多くのステータスコードが存在する場合があります。APIのドキュメントや仕様に従って正確なステータスコードとその意味を確認することが重要です。
APIのステータスコードを設計する方法
それでは、APIを設計するときに、このHTTPスターテスコードをどうやって設計すればいいですか？次は、非常に直感的なAPI設計ツールのapidogを使用して、スターテスコードを設計する方法を紹介します。
ApidogでAPIを設計して開発する時に、レスポンスの設定で、HTTPステータスコードを設計することができます。HTTPステータスコードをクリックして、ドロップリストからコードを選択することができます。また、「追加」ボタンをクリックして、異なるAPIスターテスコードを追加することもできます。
そして、各HTTPステータスコードに対して、具体的なデータ構造を直感的なUIで設計することもできますし、JSON Schema、XML Schemaなどのデータから直接にインポートすることもできますので、非常に便利です！
