例外と HTTP ステータス コード

多くの場合、一般的な HTTP ステータス コードを使用して、ユーザーの API リクエストの成功または失敗を示すことをおすすめします。たとえば、ユーザーが存在しないエンティティを取得しようとしている場合は、ID が entity_id であるエンティティが存在しないことを示す HTTP 404 ステータス コードを送信します。

一般的な HTTP ステータス コードを送信するには、エンドポイント ライブラリで提供される例外を次のように発生させることができます。

message = 'No entity with the id "%s" exists.' % entity_id
raise endpoints.NotFoundException(message)

Endpoints Frameworks で提供される例外

エンドポイント ライブラリには以下の例外があり、それぞれ特定の HTTP ステータス コードに対応しています。

例外 対応する HTTP ステータス コード
endpoints.BadRequestException HTTP 400
endpoints.UnauthorizedException HTTP 401
endpoints.ForbiddenException HTTP 403
endpoints.NotFoundException HTTP 404
endpoints.InternalServerErrorException HTTP 500

サポートされている HTTP ステータス コード

Cloud Endpoints Frameworks では、API レスポンス内で HTTP ステータス コードのサブセットがサポートされます。サポートされているコードは次の表のとおりです。

HTTP ステータス コード サポート
HTTP 2xx API メソッドから正常に戻る場合、Endpoints Frameworks では通常、HTTP 200 を想定しています。
API メソッドのレスポンス タイプが VoidMessage の場合や、API メソッドの戻り値が None である場合は、代わりに HTTP 204 が設定されます。
HTTP 3xx HTTP 3xx コードはサポートされません。HTTP 3xx コードを使用すると、HTTP 404 が返されます。
HTTP 4xx 次の HTTP 4xx コードのみがサポートされます。
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
次に挙げるものを除き、その他の HTTP 4xx コードにはエラー 404 が返されます。
  • 405 は 501 として返します
  • 408 は 503 として返します
HTTP 5xx HTTP 5xx ステータス コードはすべて、クライアント レスポンスにおいて HTTP 503 に変換されます。

独自の例外クラスの作成

その他の HTTP ステータス コードに対応するその他の例外クラスを作成するには、endpoints.ServiceException をサブクラス化して作成できます。以下のスニペットは、HTTP 409 ステータス コードを表す例外クラスの作成方法を示しています。

import endpoints
import httplib

class ConflictException(endpoints.ServiceException):
  """Conflict exception that is mapped to a 409 response."""
  http_status = httplib.CONFLICT