Ausnahmen und HTTP-Statuscodes

Auf dieser Seite sind die Ausnahmen aufgelistet, die von der endpoints-Bibliothek zur Verfügung gestellt werden, sowie die von Cloud Endpoints Frameworks unterstützten HTTP-Statuscodes.

In vielen Situationen möchten Sie vielleicht gängige HTTP-Statuscodes verwenden, um einem Nutzer anzuzeigen, ob seine API-Anfrage erfolgreich war oder nicht. Wenn ein Nutzer beispielsweise versucht, eine nicht vorhandene Entität abzurufen, können Sie einen HTTP-404-Statuscode senden und damit mitteilen, dass keine Entität mit der ID entityIdvorhanden ist.

Zum Senden gängiger HTTP-Statuscodes können Sie wie folgt eine von der endpoints-Bibliothek bereitgestellte Ausnahme auslösen:

throw new NotFoundException(user.getEmail());

Von Endpoints Frameworks bereitgestellte Ausnahmen

Endpoints Frameworks gibt die folgenden Ausnahmen aus. Diese entsprechen spezifischen HTTP-Statuscodes:

Ausnahme	Zugehöriger HTTP-Statuscode
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

Unterstützte HTTP-Statuscodes

Cloud Endpoints Frameworks unterstützt in API-Antworten einen Teil der HTTP-Statuscodes. Die unterstützten Codes werden in der folgenden Tabelle beschrieben.

HTTP-Statuscodes	Support
HTTP 2xx	Endpoints Frameworks geht bei einer erfolgreichen Rückgabe der API-Methode normalerweise von HTTP 200 aus. Wenn der Antworttyp der API-Methode void oder der Rückgabewert der API-Methode null ist, wird stattdessen HTTP 204 festgelegt.
HTTP 3xx	HTTP 3xx-Codes werden nicht unterstützt. Bei der Verwendung von HTTP 3xx-Codes wird HTTP 404 zurückgegeben.
HTTP 4xx	Es werden nur die folgenden HTTP 4xx-Codes unterstützt: 400 401 403 404 409 410 412 413 Für alle anderen HTTP 4xx-Codes wird der Fehler 404 zurückgegeben. Dies gilt jedoch nicht für die folgenden Codes: Für 405 wird 501 zurückgegeben. Für 408 wird 503 zurückgegeben.
HTTP 5xx	Alle HTTP 5xx-Statuscodes werden in der Client-Antwort in HTTP 503 konvertiert.

Wichtig: Verwenden Sie keine benutzerdefinierten Ausnahmeklassen, um HTTP 2xx-Codes zurückzugeben. Endpoints Frameworks bietet keine Unterstützung für die Rückgabe von HTTP 201 oder anderer 2xx-Codes außer HTTP 200 und HTTP 204, wie in der vorherigen Tabelle beschrieben.

Eigene Ausnahmeklassen erstellen

Wenn Sie für andere HTTP-Statuscodes andere Ausnahmeklassen erstellen möchten, müssen Sie dazu abgeleitete Klassen von com.google.api.server.spi.ServiceException erstellen. Das folgende Snippet zeigt, wie Sie eine Ausnahmeklasse erstellen, die den Statuscode HTTP 408 repräsentiert:

import com.google.api.server.spi.ServiceException;

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}

Wichtig: Eine nicht abgefangene Ausnahme in Ihrer Anwendung führt zu einem HTTP-503-Fehler von der Cloud Endpoints API, es sei denn, sie erweitert com.google.api.server.spi.ServiceException.

Nicht unterstützte HTTP-Statuscodes verwenden

Sie können auch HTTP-Statuscodes verwenden, die nicht in der obigen Liste der unterstützten Codes enthalten sind. Beachten Sie, dass in diesem Fall nicht beabsichtigte Folgen für Clientbibliotheken mit Zugriff auf die API entstehen können. Wenn Sie nicht unterstützte Fehlercodes verwenden möchten, erstellen Sie wie im vorherigen Abschnitt beschrieben eine eigene Ausnahmeklasse und fügen Sie einen neuen Servlet-Initialisierungsparameter enableExceptionCompatibility zu EndpointsServlet hinzu.

  <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>