Exceptions et codes d'état HTTP

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 pour indiquer qu'aucune entité portant l'ID entity_id n'existe.

Important : Une exception non détectée dans votre application génère une erreur HTTP 503 de votre API backend.

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

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

Exceptions fournies par Endpoints Frameworks

La bibliothèque Endpoints Framework fournit les exceptions suivantes, correspondant à des codes d'état HTTP spécifiques :

Exception	Code d'état HTTP correspondant
endpoints.BadRequestException	HTTP 400
endpoints.UnauthorizedException	HTTP 401
endpoints.ForbiddenException	HTTP 403
endpoints.NotFoundException	HTTP 404
endpoints.InternalServerErrorException	HTTP 500

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 VoidMessage ou si la valeur renvoyée est None, 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 endpoints.ServiceException. L'extrait de code suivant montre comment créer une classe d'exceptions qui représente un code d'état HTTP 409 :

import endpoints
import httplib

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