Exceptions et codes d'état HTTP

Cette page répertorie les exceptions fournies par la bibliothèque endpoints, ainsi que les codes d'état HTTP compatibles avec Cloud Endpoints Frameworks.

Dans la plupart des cas, vous devez utiliser des codes d'état HTTP courants pour indiquer le succès ou l'échec d'une requête API. Par exemple, si un utilisateur tente de récupérer une entité qui n'existe pas, vous pouvez envoyer un code d'état HTTP 404 indiquant qu'il n'existe aucune entité correspondant à l'ID entityId.

Vous pouvez envoyer des codes d'état HTTP courants en insérant une exception fournie par la bibliothèque endpoints, comme suit :

throw new NotFoundException(user.getEmail());

Exceptions fournies par Endpoints Frameworks

Endpoints Frameworks fournit les exceptions suivantes, correspondant à des codes de statut HTTP spécifiques :

Exception	Code d'état HTTP correspondant
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

Codes d'état HTTP compatibles

Cloud Endpoints Frameworks est compatible avec un sous-ensemble de codes d'état HTTP dans les réponses d'API. Le tableau suivant décrit les codes compatibles.

Codes d'état HTTP	Compatibilité
HTTP 2xx	Le code HTTP 200 est généralement utilisé par Endpoints Frameworks lorsque la méthode API aboutit. Si la réponse de la méthode API est du type void ou si la valeur renvoyée est null, le code HTTP 204 est utilisé à la place.
HTTP 3xx	Les codes HTTP 3xx ne sont pas compatibles. L'utilisation de tels codes entraîne une réponse HTTP 404.
HTTP 4xx	Seuls les codes HTTP 4xx suivants sont compatibles : 400 401 403 404 409 410 412 413 Tous les autres codes HTTP 4xx sont renvoyés en tant qu'erreurs 404, à l'exception des codes suivants : Le code HTTP 405 est renvoyé en tant qu'erreur 501. Le code HTTP 408 est renvoyé en tant qu'erreur 503.
HTTP 5xx	Tous les codes d'état HTTP 5xx sont convertis en HTTP 503 dans la réponse du client.

Important : N'utilisez pas de classes d'exceptions personnalisées pour renvoyer des codes HTTP 2xx. Endpoints Frameworks ne permet pas le renvoi du code HTTP 201 ou de tout autre code 2xx, à l'exception de HTTP 200 et HTTP 204, comme décrit ci-dessus.

Créer vos propres classes d'exceptions

Si vous souhaitez créer des classes d'exceptions pour d'autres codes d'état HTTP, vous pouvez le faire en définissant des sous-classes de com.google.api.server.spi.ServiceException. L'extrait de code suivant montre comment créer une classe d'exceptions qui représente un code d'état 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);
  }
}

Important : Une exception non détectée dans votre application entraînera une erreur HTTP 503 de votre API Cloud Endpoints, sauf si elle étend la classe com.google.api.server.spi.ServiceException.

Utiliser des codes d'état HTTP non compatibles

Il est possible d'utiliser des codes d'état HTTP qui ne figurent pas dans la liste ci-dessus. Notez que cela peut avoir des conséquences inattendues pour les bibliothèques clientes qui accèdent à l'API. Pour utiliser des codes d'erreur non compatibles, créez votre propre classe d'exceptions comme indiqué à la section précédente, et ajoutez le paramètre d'initialisation enableExceptionCompatibility au servlet 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>