Amalan Terbaik untuk Menangani Ralat API REST

1. Pengenalan

REST adalah seni bina tanpa status di mana pelanggan dapat mengakses dan memanipulasi sumber pada pelayan. Secara umum, perkhidmatan REST menggunakan HTTP untuk mengiklankan sekumpulan sumber daya yang mereka kelola dan menyediakan API yang membolehkan klien memperoleh atau mengubah keadaan sumber daya ini.

Dalam tutorial ini, kita akan belajar tentang beberapa amalan terbaik untuk menangani kesalahan REST API, termasuk pendekatan yang berguna untuk memberi pengguna maklumat yang relevan, contoh dari laman web berskala besar, dan pelaksanaan yang konkrit menggunakan contoh aplikasi Spring REST.

2. Kod Status HTTP

Semasa pelanggan membuat permintaan ke pelayan HTTP - dan pelayan berjaya menerima permintaan itu - pelayan mesti memberitahu klien jika permintaan itu berjaya ditangani atau tidak . HTTP mencapainya dengan lima kategori kod status:

  • Tahap 100 (Maklumat) - Pelayan mengakui permintaan
  • Tahap 200 (Kejayaan) - Pelayan menyelesaikan permintaan seperti yang diharapkan
  • 300-level (Redirection) - Pelanggan perlu melakukan tindakan selanjutnya untuk menyelesaikan permintaan
  • Tahap 400 (Kesalahan pelanggan) - Pelanggan menghantar permintaan yang tidak sah
  • Tahap 500 (Kesalahan pelayan) - Pelayan gagal memenuhi permintaan yang sah kerana berlaku ralat dengan pelayan

Berdasarkan kod respons, pelanggan dapat menduga hasil permintaan tertentu.

3. Kesalahan Mengendalikan

Langkah pertama dalam menangani kesilapan adalah memberikan kod status yang betul kepada pelanggan. Selain itu, kita mungkin perlu memberikan lebih banyak maklumat di badan tindak balas.

3.1. Tindak Balas Asas

Cara termudah untuk menangani kesilapan adalah bertindak balas dengan kod status yang sesuai .

Beberapa kod respons biasa termasuk:

  • 400 Permintaan Buruk - Pelanggan menghantar permintaan yang tidak sah - seperti kekurangan badan permintaan atau parameter
  • 401 Tidak Dibenar - Pelanggan gagal mengesahkan dengan pelayan
  • 403 Dilarang - Pelanggan disahkan tetapi tidak mempunyai kebenaran untuk mengakses sumber yang diminta
  • 404 Tidak Ditemui - Sumber yang diminta tidak ada
  • 412 Prasyarat Gagal - Satu atau lebih syarat dalam bidang tajuk permintaan yang dinilai salah
  • 500 Ralat Pelayan Dalaman - Ralat umum berlaku pada pelayan
  • 503 Perkhidmatan Tidak Tersedia - Perkhidmatan yang diminta tidak tersedia

Walaupun asas, kod-kod ini membolehkan pelanggan memahami sifat ralat yang berlaku. Sebagai contoh, kita tahu jika kita menerima ralat 403 bahawa kita tidak mempunyai kebenaran untuk mengakses sumber yang kita minta.

Namun, dalam banyak kes, kita perlu memberikan butiran tambahan dalam jawapan kita.

500 kesalahan menunjukkan bahawa beberapa masalah atau pengecualian berlaku pada pelayan semasa menangani permintaan. Secara amnya, kesalahan dalaman ini bukan urusan pelanggan kami.

Oleh itu, untuk meminimumkan tindak balas seperti itu kepada pelanggan, kita harus rajin berusaha menangani atau menangkap kesilapan dalaman dan bertindak balas dengan kod status lain yang sesuai, seboleh-bolehnya . Sebagai contoh, jika pengecualian berlaku kerana sumber yang diminta tidak ada, kita harus mendedahkannya sebagai ralat 404 dan bukan 500.

Ini bukan untuk mengatakan bahawa 500 tidak boleh dikembalikan, hanya harus digunakan untuk keadaan yang tidak dijangka - seperti gangguan perkhidmatan - yang menghalang pelayan untuk melaksanakan permintaan.

3.2. Respons Kesalahan Musim Semi Lalai

Prinsip-prinsip ini ada di mana-mana sehingga Spring telah mengkodifikasinya dalam mekanisme pengendalian ralat lalai.

Untuk menunjukkan, andaikan kita mempunyai aplikasi Spring REST sederhana yang menguruskan buku, dengan titik akhir untuk mengambil buku dengan IDnya:

curl -X GET -H "Accept: application/json" //localhost:8082/spring-rest/api/book/1

Sekiranya tidak ada buku dengan ID 1, kami menjangkakan pengawal kami akan membuang BookNotFoundException . Melakukan GET pada titik akhir ini, kami melihat bahawa pengecualian ini dilemparkan dan badan tindak balas adalah:

{ "timestamp":"2019-09-16T22:14:45.624+0000", "status":500, "error":"Internal Server Error", "message":"No message available", "path":"/api/book/1" }

Perhatikan bahawa pengendali ralat lalai ini merangkumi cap waktu ketika ralat berlaku, kod status HTTP, tajuk ( medan ralat ), mesej (yang kosong secara lalai), dan jalur URL di mana ralat itu berlaku.

Medan ini memberikan maklumat kepada klien atau pengembang untuk membantu menyelesaikan masalah dan juga merupakan beberapa bidang yang membentuk mekanisme pengendalian ralat standard.

Selain itu, perhatikan bahawa Spring secara automatik mengembalikan kod status HTTP 500 apabila BookNotFoundException kami dilemparkan. Walaupun beberapa API akan mengembalikan kod status 500 atau yang lain, seperti yang akan kita lihat dengan API Facebook dan Twitter - untuk semua kesilapan demi kesederhanaan, lebih baik menggunakan kod ralat yang paling spesifik apabila mungkin .

Dalam contoh kami, kami dapat menambahkan @ControllerAdvice sehingga apabila BookNotFoundException dilemparkan, API kami memberikan kembali status 404 untuk menunjukkan Tidak Ditemui dan bukannya 500 Kesalahan Pelayan Dalaman .

3.3. Maklumbalas Lebih terperinci

Seperti yang dilihat dalam contoh Spring di atas, kadangkala kod status tidak cukup untuk menunjukkan spesifik kesalahan. Apabila diperlukan, kita dapat menggunakan badan respons untuk memberi maklumat tambahan kepada pelanggan. Semasa memberikan jawapan terperinci, kami harus memasukkan:

  • Ralat - Pengecam unik untuk ralat
  • Mesej - Mesej ringkas yang boleh dibaca manusia
  • Perincian - Penjelasan ralat yang lebih panjang

Sebagai contoh, jika pelanggan menghantar permintaan dengan bukti kelayakan yang salah, kami dapat menghantar respons 401 dengan badan:

{ "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct" }

The ralat bidang tidak sepadan dengan kod sambutan . Sebaliknya, ia harus menjadi kod ralat yang unik untuk aplikasi kami. Secara amnya, tidak ada konvensi untuk bidang kesalahan , harapkan ia unik.

Usually, this field contains only alphanumerics and connecting characters, such as dashes or underscores. For example, 0001, auth-0001, and incorrect-user-pass are canonical examples of error codes.

The message portion of the body is usually considered presentable on user interfaces. Therefore we should translate this title if we support internationalization. So, if a client sends a request with an Accept-Language header corresponding to French, the title value should be translated to French.

The detail portion is intended for use by developers of clients and not the end-user, so the translation is not necessary.

Additionally, we could also provide a URL — such as the help field — that clients can follow to discover more information:

{ "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct", "help": "//example.com/help/error/auth-0001" }

Sometimes, we may want to report more than one error for a request. In this case, we should return the errors in a list:

{ "errors": [ { "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct", "help": "//example.com/help/error/auth-0001" }, ... ] }

And when a single error occurs, we respond with a list containing one element. Note that responding with multiple errors may be too complicated for simple applications. In many cases, responding with the first or most significant error is sufficient.

3.4. Standardized Response Bodies

While most REST APIs follow similar conventions, specifics usually vary, including the names of fields and the information included in the response body. These differences make it difficult for libraries and frameworks to handle errors uniformly.

In an effort to standardize REST API error handling, the IETF devised RFC 7807, which creates a generalized error-handling schema.

This schema is composed of five parts:

  1. type — A URI identifier that categorizes the error
  2. title — A brief, human-readable message about the error
  3. status — The HTTP response code (optional)
  4. detail — A human-readable explanation of the error
  5. instance — A URI that identifies the specific occurrence of the error

Instead of using our custom error response body, we can convert our body to:

{ "type": "/errors/incorrect-user-pass", "title": "Incorrect username or password.", "status": 401, "detail": "Authentication failed due to incorrect username or password.", "instance": "/login/log/abc123" }

Note that the type field categorizes the type of error, while instance identifies a specific occurrence of the error in a similar fashion to classes and objects, respectively.

By using URIs, clients can follow these paths to find more information about the error in the same way that HATEOAS links can be used to navigate a REST API.

Adhering to RFC 7807 is optional, but it is advantageous if uniformity is desired.

4. Examples

The above practices are common throughout some of the most popular REST APIs. While the specific names of fields or formats may vary between sites, the general patterns are nearly universal.

4.1. Twitter

For example, let's send a GET request without supplying the required authentication data:

curl -X GET //api.twitter.com/1.1/statuses/update.json?include_entities=true

The Twitter API responds with an error with the following body:

{ "errors": [ { "code":215, "message":"Bad Authentication data." } ] }

This response includes a list containing a single error, with its error code and message. In Twitter's case, no detailed message is present and a general error — rather than a more specific 401 error — is used to denote that authentication failed.

Sometimes a more general status code is easier to implement, as we'll see in our Spring example below. It allows developers to catch groups of exceptions and not differentiate the status code that should be returned. When possible, though, the most specific status code should be used.

4.2. Facebook

Similar to Twitter, Facebook's Graph REST API also includes detailed information in its responses.

For example, let's perform a POST request to authenticate with the Facebook Graph API:

curl -X GET //graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

We receive the following error:

{ "error": { "message": "Missing redirect_uri parameter.", "type": "OAuthException", "code": 191, "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ" } }

Like Twitter, Facebook also uses a generic error — rather than a more specific 400-level error — to denote a failure. In addition to a message and numeric code, Facebook also includes a type field that categorizes the error and a trace ID (fbtrace_id) that acts as an internal support identifier.

5. Conclusion

In this article, we examined some of the best practices of REST API error handling, including:

  • Providing specific status codes
  • Including additional information in response bodies
  • Handling exceptions in a uniform manner

While the details of error handling will vary by application, these general principles apply to nearly all REST APIs and should be adhered to when possible.

Ini bukan sahaja membolehkan klien menangani kesalahan secara konsisten, tetapi juga mempermudah kod yang kita buat semasa melaksanakan REST API.

Kod yang dirujuk dalam artikel ini terdapat di GitHub.