Eccezioni e codici di stato HTTP

In questa pagina sono elencate le eccezioni fornite dalla libreria endpoints e i codici di stato HTTP supportati da Cloud Endpoints Frameworks.

In molte situazioni, è consigliabile utilizzare codici di stato HTTP comuni per indicare l'esito positivo o negativo della richiesta API di un utente. Ad esempio, se un utente sta tentando di recuperare un'entità che non esiste, può essere opportuno inviare un codice di stato HTTP 404 per comunicare che non esiste alcuna entità con ID entityId.

Puoi inviare codici di stato HTTP comuni generando 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

Cloud Endpoints Frameworks supporta un sottoinsieme di codici di stato HTTP nelle risposte dell'API. Nella tabella seguente sono descritti i codici supportati.

Codici di stato HTTP Assistenza
HTTP 2xx In genere HTTP 200 viene utilizzato da Endpoints Frameworks se il metodo API restituisce correttamente.
Se il tipo di risposta del metodo API è void o il valore restituito del metodo API è null , viene impostato HTTP 204.
HTTP 3xx I codici HTTP 3xx non sono supportati. L'utilizzo di qualsiasi codice HTTP 3xx genera una risposta 404 HTTP.
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 dei seguenti:
  • 405 viene restituito come 501
  • 408 viene restituito come 503
HTTP 5xx Tutti i codici di stato HTTP 5xx vengono convertiti in HTTP 503 nella risposta del client.

Creazione di classi di eccezione personalizzate

Se vuoi creare altre classi di eccezione per altri codici di stato HTTP, devi eseguire la sottoclasse com.google.api.server.spi.ServiceException. Lo snippet seguente 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);
  }
}

Utilizzo di codici di stato HTTP non supportati

Puoi utilizzare codici di stato HTTP che non sono presenti nell'elenco precedente supportato. Tieni presente che, se decidi di farlo, potresti avere conseguenze indesiderate per le librerie client che accedono all'API. Per utilizzare codici di errore non supportati, crea una classe di eccezione personalizzata, come descritto nella sezione precedente, e aggiungi un nuovo parametro di inizializzazione dei servlet enableExceptionCompatibility in 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>