Eccezioni e codici di stato HTTP

In questa pagina sono elencate le eccezioni fornite dalla libreria endpoints, nonché Codici di stato HTTP supportati da Cloud Endpoints Frameworks.

In molte situazioni, potresti voler utilizzare codici di stato HTTP comuni per indicare l'esito positivo o negativo di una richiesta API di un utente. Ad esempio, se un utente di recuperare un'entità che non esiste, potresti inviare Codice di stato HTTP 404 per indicare che non esiste nessuna entità con ID: entityId.

Puoi inviare codici di stato HTTP comuni lanciando un'eccezione fornita dalla libreria endpoints come segue:

throw new NotFoundException(user.getEmail());

Eccezioni fornite da Endpoints Frameworks

Endpoints Frameworks fornisce le seguenti eccezioni, corrispondenti a codici di stato HTTP specifici:

Eccezione	Codice di stato HTTP corrispondente
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

Codici di stato HTTP supportati

I framework Cloud Endpoints supportano un sottoinsieme di codici di stato HTTP nelle risposte dell'API. La tabella seguente descrive i codici supportati.

Codici di stato HTTP	Assistenza
HTTP 2xx	Il valore HTTP 200 in genere viene utilizzato da Endpoints Frameworks se il metodo API viene restituito correttamente. Se il tipo di risposta del metodo API è void o il valore restituito del metodo API è null , viene impostato invece HTTP 204.
HTTP 3xx	I codici HTTP 3xx non sono supportati. L'utilizzo di qualsiasi codice HTTP 3xx genera una risposta HTTP 404.
HTTP 4xx	Sono supportati solo i seguenti codici HTTP 4xx: 400 401 403 404 409 410 412 413 Qualsiasi altro codice HTTP 4xx viene restituito come errore 404, ad eccezione di quanto segue: 405 viene restituito come 501 408 viene restituito come 503
Errori HTTP 5xx	Tutti i codici di stato HTTP 5xx vengono convertiti in HTTP 503 nella risposta del client.

Importante: non utilizzare classi di eccezione personalizzate per restituire codici HTTP 2xx. Endpoints Frameworks non supporta la restituzione di HTTP 201 o di qualsiasi altro Codici 2xx tranne HTTP 200 e HTTP 204 come descritto nella tabella precedente.

Creazione di classi di eccezioni personalizzate

Se vuoi creare altre classi di eccezioni per altri codici di stato HTTP, creare una sottoclasse com.google.api.server.spi.ServiceException. La lo snippet riportato di seguito mostra come creare una classe di eccezione che rappresenta un Codice di stato 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);
  }
}

Importante: un'eccezione non rilevata nell'applicazione genera un errore HTTP 503 dall'API Cloud Endpoints, a meno che non espanda com.google.api.server.spi.ServiceException.

Utilizzo di codici di stato HTTP non supportati

È possibile utilizzare codici di stato HTTP non presenti nell'elenco supportato precedente. Tieni presente che, se decidi di farlo, potrebbero esserci conseguenze indesiderate per le librerie client che accedono all'API. Per utilizzare codici di errore non supportati: creare la tua classe di eccezione, come descritto nella sezione precedente, e aggiungi un nuovo parametro di inizializzazione servlet enableExceptionCompatibility a 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>