Kode status HTTP dan pengecualian

Halaman ini mencantumkan pengecualian yang diberikan 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 entity yang tidak ada, Anda dapat mengirim kode status HTTP 404 yang menyatakan bahwa tidak ada entity 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 diberikan oleh Framework Endpoints

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

Pengecualian	Kode status HTTP yang sesuai
com.google.api.server.spi.response.BadRequestException	400 HTTP
com.google.api.server.spi.response.UnauthorizedException	401 HTTP
com.google.api.server.spi.response.ForbiddenException	403 HTTP
com.google.api.server.spi.response.NotFoundException	404 HTTP
com.google.api.server.spi.response.ConflictException	409 HTTP
com.google.api.server.spi.response.InternalServerErrorException	500 HTTP
com.google.api.server.spi.response.ServiceUnavailableException	503 HTTP

Kode status HTTP yang didukung

Cloud Endpoints Frameworks mendukung subset kode status HTTP dalam respons API. Tabel berikut menjelaskan kode yang didukung.

Kode status HTTP	Support
HTTP 2xx	200 HTTP biasanya diasumsikan oleh Framework Endpoint jika metode API berhasil ditampilkan. Jika jenis respons metode API adalah void atau nilai yang ditampilkan metode API adalah null , HTTP 204 akan ditetapkan.
HTTP 3xx	Kode 3xx HTTP tidak didukung. Penggunaan kode HTTP 3xx apa pun akan menghasilkan respons 404 HTTP.
HTTP 4xx	Hanya kode HTTP 4xx berikut yang didukung: 400 401 403 404 409 410 412 413 Kode HTTP 4xx lainnya ditampilkan sebagai error 404, kecuali untuk hal 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 Endpoints tidak mendukung ditampilkannya 201 HTTP atau kode 2xx lainnya kecuali 200 HTTP 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 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);
  }
}

Penting: Pengecualian yang tidak tertangkap dalam aplikasi Anda menyebabkan error 503 HTTP dari Cloud Endpoints API Anda, kecuali jika pengecualian tersebut 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. Perlu diperhatikan bahwa jika Anda memutuskan untuk melakukannya, tindakan ini mungkin menimbulkan 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>