Pengecualian dan kode status HTTP

Halaman ini mencantumkan pengecualian yang disediakan oleh library endpoints serta kode status HTTP yang didukung oleh Framework Cloud Endpoints.

Dalam banyak situasi, Anda mungkin ingin menggunakan kode status HTTP umum untuk menunjukkan keberhasilan atau kegagalan permintaan API pengguna. Misalnya, jika pengguna mencoba mengambil entitas yang tidak ada, Anda dapat mengirim kode status HTTP 404 untuk menyatakan bahwa tidak ada entitas dengan ID: entityId.

Anda dapat mengirim kode status HTTP umum dengan menampilkan pengecualian yang disediakan oleh library endpoints sebagai berikut:

throw new NotFoundException(user.getEmail());

Pengecualian yang disediakan oleh Framework Endpoints

Framework Endpoint menyediakan pengecualian berikut, yang sesuai dengan kode status HTTP tertentu:

Pengecualian	Kode status HTTP yang sesuai
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

Kode status HTTP yang didukung

Framework Cloud Endpoints mendukung sebagian kode status HTTP dalam respons API. Tabel berikut menjelaskan kode yang didukung.

Kode status HTTP	Dukungan
HTTP 2xx	HTTP 200 biasanya diasumsikan oleh Framework Endpoint jika metode API berhasil ditampilkan. Jika jenis respons metode API adalah void atau nilai yang ditampilkan dari metode API adalah null , HTTP 204 akan ditetapkan.
HTTP 3xx	Kode HTTP 3xx tidak didukung. Penggunaan kode HTTP 3xx akan menghasilkan respons HTTP 404.
HTTP 4xx	Hanya kode HTTP 4xx berikut yang didukung: 400 401 403 404 409 410 412 413 Kode 4xx HTTP lainnya akan ditampilkan sebagai error 404, kecuali untuk kode berikut: 405 ditampilkan sebagai 501 408 ditampilkan sebagai 503
HTTP 5xx	Semua kode status HTTP 5xx dikonversi menjadi HTTP 503 dalam respons klien.

Penting: Jangan gunakan class pengecualian kustom untuk menampilkan kode HTTP 2xx. Framework Endpoint tidak mendukung kode 2xx HTTP 201 atau kode lainnya kecuali HTTP 200 dan HTTP 204 seperti yang dijelaskan dalam tabel sebelumnya.

Membuat class pengecualian Anda sendiri

Jika ingin membuat class pengecualian lain untuk kode status HTTP lainnya, Anda harus membuat subclass com.google.api.server.spi.ServiceException. Cuplikan berikut menunjukkan cara membuat class pengecualian yang mewakili kode status 408 HTTP:

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

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

Penting: Pengecualian yang tidak tertangkap dalam aplikasi Anda akan menyebabkan error 503 HTTP dari Cloud Endpoints API, kecuali jika memperluas com.google.api.server.spi.ServiceException.

Menggunakan kode status HTTP yang tidak didukung

Anda dapat menggunakan kode status HTTP yang tidak ada dalam daftar yang didukung sebelumnya. Perhatikan bahwa jika Anda memutuskan untuk melakukannya, tindakan ini mungkin memiliki konsekuensi yang tidak diinginkan untuk library klien yang mengakses API. Untuk menggunakan kode error yang tidak didukung, buat class pengecualian Anda sendiri, seperti yang dijelaskan di bagian sebelumnya, dan tambahkan parameter inisialisasi servlet baru enableExceptionCompatibility ke 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>