Exceções e códigos de estado HTTP

Em muitas situações, pode querer usar códigos de estado HTTP comuns para indicar o êxito ou a falha de um pedido de API de um utilizador. Por exemplo, se um utilizador estiver a tentar obter uma entidade que não existe, é recomendável enviar um código de estado HTTP 404 a indicar que não existe nenhuma entidade com o ID entity_id.

Importante: uma exceção não capturada na sua aplicação resulta num erro HTTP 503 da sua API de back-end.

Pode enviar esses códigos de estado HTTP comuns gerando uma exceção fornecida pela biblioteca de pontos finais da seguinte forma:

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

Exceções fornecidas pelos frameworks de pontos finais

A biblioteca de pontos finais fornece as seguintes exceções, correspondentes a códigos de estado HTTP específicos:

Exceção	Código de estado 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 estado HTTP suportados

Os frameworks do Cloud Endpoints suportam um subconjunto de códigos de estado HTTP nas respostas da API. A tabela seguinte descreve os códigos suportados.

Códigos de estado HTTP	Apoio técnico
HTTP 2xx	Normalmente, o HTTP 200 é assumido pelos Endpoints Frameworks se o método da API for devolvido com êxito. Se o tipo de resposta do método da API for VoidMessage ou o valor de retorno do método da API for None , é definido o HTTP 204.
HTTP 3xx	Os códigos HTTP 3xx não são suportados. A utilização de códigos HTTP 3xx resulta numa resposta HTTP 404.
HTTP 4xx	Apenas são suportados os seguintes códigos HTTP 4xx: 400 401 403 404 409 410 412 413 Quaisquer outros códigos HTTP 4xx são devolvidos como erro 404, exceto os seguintes: 405 é devolvido como 501 408 é devolvido como 503
HTTP 5xx	Todos os códigos de estado HTTP 5xx são convertidos em HTTP 503 na resposta do cliente.

Importante: não use classes de exceções personalizadas para devolver códigos HTTP 2xx. O Endpoints Frameworks não suporta a devolução de HTTP 201 nem de quaisquer outros códigos 2xx, exceto HTTP 200 e HTTP 204, conforme descrito na tabela anterior.

Criar as suas próprias classes de exceções

Se quiser criar outras classes de exceções para outros códigos de estado HTTP, pode fazê-lo criando subclasses de endpoints.ServiceException. O fragmento seguinte mostra como criar uma classe de exceção que representa um código de estado HTTP 409:

import endpoints
import httplib

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