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

ここでは、endpoints ライブラリにより提供される例外と、Cloud Endpoints Frameworks でサポートされている HTTP ステータス コードのリストを示します。

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

次のように、endpoints ライブラリが提供する例外を指定することで、一般的な HTTP ステータス コードを送信できます。

throw new NotFoundException(user.getEmail());

Endpoints Frameworks が提供する例外

Endpoints Frameworks は以下の例外を提供します。それぞれ特定の HTTP ステータス コードに対応しています。

例外 対応する HTTP ステータス コード
com.google.api.server.spi.response.BadRequestException HTTP 400
com.google.api.server.spi.response.UnauthorizedException HTTP 401
com.google.api.server.spi.response.ForbiddenException HTTP 403
com.google.api.server.spi.response.NotFoundException HTTP 404
com.google.api.server.spi.response.ConflictException HTTP 409
com.google.api.server.spi.response.InternalServerErrorException HTTP 500
com.google.api.server.spi.response.ServiceUnavailableException HTTP 503

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

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

HTTP ステータス コード サポート
HTTP 2xx API メソッドから正常に戻る場合、Endpoints Frameworks では通常、HTTP 200 を想定しています。
API メソッドのレスポンス タイプが void の場合や、API メソッドの戻り値が null である場合は、代わりに 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 ステータス コードに対応する他の例外クラスを作成するには、com.google.api.server.spi.ServiceException をサブクラス化する必要があります。次のスニペットは、HTTP 408 ステータス コードを表す例外クラスの作成方法を示しています。

import com.google.api.server.spi.ServiceException;

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}

サポートされていない HTTP ステータス コードを使用する

前述のサポートされている HTTP ステータス コードのリストにないコードを使用することは可能です。そのようなコードを使用する場合、API にアクセスするクライアント ライブラリで予期しない結果が生じる可能性があるので、ご注意ください。サポートされていないエラーコードを使用するには、前のセクションで説明した独自の例外クラスを作成し、次のように新しいサーブレット初期化パラメータ enableExceptionCompatibility を EndpointsServlet に追加します。

  <servlet>
    <servlet-name>com.google.api.server.spi.EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
      <param-name>services</param-name>
      <param-value>...</param-value>
    </init-param>
    <init-param>
      <param-name>enableExceptionCompatibility</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>