Exceções e códigos de status HTTP

Em muitas situações, convém usar códigos de status HTTP comuns para indicar o sucesso ou a falha da solicitação de API de um usuário. Por exemplo, se um usuário está tentando recuperar uma entidade que não existe, você pode querer enviar um código de status HTTP 404 para dizer que nenhuma entidade com o ID entity_id existe.

É possível enviar esses códigos de status HTTP comuns gerando uma exceção fornecida pela biblioteca do Endpoints desta maneira:

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

Exceções fornecidas pelo Endpoints Frameworks

A biblioteca do Endpoints fornece as exceções a seguir, correspondentes a códigos de status HTTP específicos:

Exceção Código de status HTTP correspondente
endpoints.BadRequestException HTTP 400
endpoints.UnauthorizedException HTTP 401
endpoints.ForbiddenException HTTP 403
endpoints.NotFoundException HTTP 404
endpoints.InternalServerErrorException HTTP 500

Códigos de status HTTP compatíveis

O Cloud Endpoints Frameworks é compatível com um subconjunto de códigos de status HTTP nas respostas da API. A tabela a seguir descreve os códigos compatíveis.

Códigos de status HTTP Compatibilidade
HTTP 2xx HTTP 200 é normalmente assumido pelo Endpoints Frameworks se o método da API retornar com sucesso.
Se o tipo de resposta do método da API for VoidMessage ou o valor de retorno do método da API for None, HTTP 204 é definido em vez disso.
HTTP 3xx Códigos HTTP 3xx não são compatíveis. O uso de qualquer código HTTP 3xx resulta em uma resposta HTTP 404.
HTTP 4xx Apenas os seguintes códigos HTTP 4xx são compatíveis:
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
Quaisquer outros códigos HTTP 4xx são retornados como erro 404, com exceção dos seguintes:
  • 405 é retornado como 501
  • 408 é retornado como 503
HTTP 5xx Todos os códigos de status HTTP 5xx são convertidos em HTTP 503 na resposta do cliente.

Como criar classes de exceção próprias

Se você quiser criar outras classes de exceção para outros códigos de status HTTP, poderá fazer isso com a subclasse endpoints.ServiceException. O snippet a seguir mostra como criar uma classe de exceção que representa um código de status HTTP 409.

import endpoints
import httplib

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