Bir REST API, bir sorgunun var olmayan bir nesneye başvurduğunu belirtmek için 500 Dahili Sunucu Hatası döndürmeli midir?

Çok sayıda IoT aygıtının verilerini işleyen bir sunucuda bulunan bir REST API ile çalışıyorum.

Görevim, söz konusu cihazlar hakkında belirli performans bilgilerini toplamak için API'yi kullanarak sunucuyu sorgulamak.

Bir örnekte, kullanılabilir cihazların ve bunlara karşılık gelen tanımlayıcıların bir listesini edindim, daha sonra bu tanımlayıcıları (GUID'ler) kullanarak daha fazla ayrıntı için sunucuyu sorguladım.

Sunucu 500 Internal Server Errorbu kimliklerden birinde bir sorgu için döndürüyor . Uygulamamda bir istisna atıldı ve hatayla ilgili ayrıntıları göremiyorum. Yanıtı Postman'la daha yakından incelersem, sunucunun aşağıdakileri içeren gövdede JSON'u iade ettiğini görebilirim:

errorMessage: "This ID does not exist".

Sunucunun kimliğe başlamasını sağladığı gerçeğini göz ardı edin - bu, geliştirici için ayrı bir sorundur.

Bir REST API'sinin 500 Internal Server Error, bir sorgunun var olmayan bir nesneye başvurduğunu bildirmesi için döndürmesi gerekir mi? Benim düşünceme göre, HTTP cevap kodları kesinlikle API'nin iç mekaniğinden ziyade REST çağrısının durumuna atıfta bulunmalıdır. İlgili 200 OKAPI’ye özel bir hata ve açıklama içeren bir yanıt beklerdim .

Bana göre, REST çağrısının nasıl yapılandırıldığına bağlı olarak beklentide potansiyel bir fark var.

Bu örnekleri göz önünde bulundurun:

1. http://example.com/restapi/deviceinfo?id=123
2. http://example.com/restapi/device/123/info

İlk durumda, cihaz kimliği bir GET değişkeni olarak iletilir. Bir 404 veya 500, yolun ( /restapi/deviceinfo) bulunmadığını veya bir sunucu hatasıyla sonuçlandığını gösterir.

İkinci durumda, cihaz kimliği URL'nin bir parçasıdır. Daha anlayışlı olurdum 404 Not Found, ama yine de yolun hangi kısımlarının son noktalara karşı değişken olarak yorumlandığına dayanarak tartışabilirim.

404 yanıtın burada en iyi anlamsal eşleşme olduğunu düşünüyorum, çünkü bulmaya çalıştığınız kaynak (sorgu için kullanılan URI tarafından gösterildiği gibi) bulunamadı. Vücutta bir hata yükünün geri verilmesi makul, ancak zorunlu değil.

RFC 2616'ya göre , 404 durum kodunun tanımı şöyledir:

10.4.5 404 Bulunamadı
Sunucu, Request-URI ile eşleşen hiçbir şey bulamadı. Koşulun geçici mi yoksa kalıcı mı olduğuna dair bir gösterge yok. Sunucu, dahili olarak yapılandırılabilir bazı mekanizmalar yoluyla eski bir kaynağın kalıcı olarak kullanılamadığını ve yönlendirme adresi olmadığını bilirse, 410 (Gitti) durum kodu kullanılmalıdır. Bu durum kodu, sunucu isteğin tam olarak neden reddedildiğini açıklamak istemediğinde veya başka bir cevap verilmediğinde kullanılır.

Örneklerini kullanacağım.

http://example.com/restapi/deviceinfo?id=123

Bitiş noktası bir json dizisi döndürürse , 200 OKsonuç bulunamamışsa , en iyi seçenek boş bir dizidir.

Uç nokta bir dönmek için tasarlanmıştır Eğer tek bir sonuç , benim seçimim olurdu 404 NOT FOUND, benim için son nokta bu tür doğru sözdizimi, çünkü: http://example.com/restapi/deviceinfo/123. Genellikle istek filtrelemeyi sadece filtreleme için ve uç noktam bir dizi döndürdüğünde kullanırım.

http://example.com/restapi/device/123/info

Bence bu soru zaten burada cevaplandı . POST veya GET, 404 NOT FOUNDkaynak 123bulunamadığı için daha iyi bir seçim gibi görünüyor .

Her iki durumda da, isteğin tamamlanmadığını açıklamanın gerekliliğini göremiyorum. İstek bilgisi ve HTTP kodu zaten nedenini açıklıyor.

HTTP 404 Doğru, çünkü sunucu müşterinin istediği kaynağı anlıyor ancak bu kaynağa sahip değil.

Bir "REST API" ile çalışıyor olmanız anahtardır. API, bir işlevi yerine getirmeyen bir Hazırlık Durumu Transferi gerçekleştiriyor gibi davranmalıdır. (Tabii ki, "REST" terimi daha geniş bir anlam kazanmıştır, ancak burada kelimenin tam anlamını iyi etki için kullanabilirsiniz.) Müşteri, URL tarafından açıklanan bir kaynağın durumunu istedi http://example.com/restapi/device/123/info. Bir querystring ( /deviceinfo?id=123) durumu değiştirmez. Sunucu, cihazın 123 durumunu transfer etmek istediğinizi biliyor, ancak bunu bilinen bir kaynak olarak tanımıyor. Dolayısıyla HTTP 404.

Burada tartışılan diğer olası cevapların da özel anlamları vardır:

• HTTP 200- Senin için devlet aldık; Tepki gövdesinde.
• HTTP 204- Senin için devlet aldık; boş.
• HTTP 400- Hangi kaynaktan bahsettiğini söyleyemiyoruz. URL’nizi düzeltin.
• HTTP 500- Arızalıyız. Senin suçun değil.

Bkz. RFC 2616 Sn. Uygun olduğu şekilde 10.

Sunucunun bir hatayla karşılaştığını ve isteği tamamlayamadığını belirtmek için genellikle 5xx hatası kullanılır. Sunucu isteği alırsa, başarıyla ayrıştırır ve daha sonra 5xx hatası vermemesi gereken işini yapar.

Bir sorgu sonuç vermezse ne döneceğine dair herhangi bir sözleşme olup olmadığından emin değilim. Ne tarif ettiğinizi (bir mesaj içeren gövdeli bir 200) ve sonuçların bulunamadığını belirten bir 404'ü gördüm. 200 muhtemelen en mantıklı olanıdır - istek başarıyla tamamlandı ve müşterinin isteğiyle veya isteği işleyen sunucuda hiçbir sorun yoktu. Bir kuruluş müşteriye bir mesaj iletebilir.

Her iki örneğinize ( http://example.com/restapi/deviceinfo?id=123ve http://example.com/restapi/device/123/info) aynı şekilde davranırdım - bu 123bir parametredir. Her iki durum da, ID 123'e sahip bir cihaz için cihaz bilgisi almak için bir talep yapılandırmanın farklı yollarıdır.

İlk önce yetkilendirme ve kimlik doğrulamayı düşünürdüm. Kullanıcı uygun izinlere sahip değilse, uygun olarak bir 403 veya 401 döndürürdüm. "Yetkisiz" olarak adlandırılmasına rağmen, benim anladığım kadarıyla 401 kimlik doğrulama ile ilgili ve 403 izinsiz veya izin verilmeyen hakkında. Tüm kimlik doğrulama ve yetkilendirme hataları için sadece 403'e sadık kalmak isteseydiniz, burada çok seçici olmazdım.

Sonra kimliği idare ederim. Örneğinize göre, sayısal bir kimlik gibi görünüyor. Sayısal olmayan bir değer verilirse, 400 değerini döndürürüm. Parametre muhtemelen geçerli bir aygıt tanımlayıcısı olabilirse, işleme devam edeceğim. Başka argümanlar olsaydı, burada da kontrol edilirdi. Yanıt kuruluşundan isteğin neden kötü olduğu konusunda uygun bilgiler içermesini beklerdim.

Tüm parametreler geçerli olsaydı, isteği işleme koymaya başlardım. Sistem veya herhangi bir bağımlılık (bir veritabanı, bir üçüncü taraf hizmeti, başka bir dahili hizmet) mevcut değilse, 5xx kodunu döndürürdüm - 503 belirli olurdu, ancak 500 de kabul edilebilirdi. Her iki durumda da, ek detayları olan bir beden iade ediyorum. Harici bir bağımlılık 408 İstek Zaman Aşımı bildirirse, bunu yiyeceğim ve müşterime 500 iade edeceğim ve müşterinin yalnızca sistemime istek zaman aşımına uğradığında 408 alabilmesine izin vereceğim. Sistem isteği yerine getirebiliyorsa, 200 kişiyi ve uygun bedeni iade ederim.

204 bazı durumlarda yararlı olabilir, ancak bir yanıt gövdesi göndermenizi engeller. Özellikle bir API ayarında, bir günlüğe kaydetme veya raporlama mekanizmasına beslenebilecek bilgileri içeren bir yanıt kuruluşu göndermek çoğu durumda verilecek doğru karar gibi görünmektedir.

Bir 404'ün döndürüleceği tek süre, sunucunun bir /deviceinfobitiş noktası veya bir /device/:id/infobitiş noktası olmamasıydı .

Bulunamayan kaynakla aynı olduğu bulunmayan bir kimliği değerlendirmezdim. Kaynak, belirli bir cihazın cihaz bilgisidir (örneğinizde). Bir 404 döndürmek, kaynağın (cihaz bilgisi) bulunmadığı anlamına gelir. Uygun bir gövdeye sahip bir 200, sistemin gerçekten cihaz bilgisi sağlayabileceği anlamına gelir. Belirtilen kimliğe sahip bir cihaz olabilir veya olmayabilir.

500 serisi bir HTTP hatası bir sunucu arızasını belirtir. Bunun dışında 501 Not Implementedve 505 HTTP Version Not Supportedbu hata kodlarını kullanmak, talebi daha sonra tekrar denemenin başarılı olabileceği fikrini taşır (ancak 503 Service Unavailablebunu açıkça ifade etse de ). İdeal olarak, bir sunucu hiçbir zaman bu kodlardan birini üretmemelidir, ancak hatasız yazılım yazma ve sunucuyu sınırsız kaynaklar sağlama zorunluluğu, zaman zaman bunlara ihtiyaç duyacağınız anlamına gelir.

Bir "nesne yok" sonucu için, büyük olasılıkla 404 Not Found(istek adına göre bir nesne olduğunda) ya 200 Successda boş bir sonuç gövdesiyle (niteliklere göre bir nesne ararken) geri dönmelisiniz. 204 No Contentcazip görünüyor, ancak bunu yalnızca bir cevap organının eksikliğinin beklenen sonuç olduğu durumlar için kullanırdım.

API'nizin bir müşterisi olarak şu aramalardan birini yaptığımda:

1. http://example.com/restapi/deviceinfo?id=123
2. http://example.com/restapi/device/123/info

DeviceInfoİster resmi bir tür isterse sadece belgelenmiş bir "ördek türü" kuralına uyan bir şey olsun, bir nesneyi (veya yine de belirli bir türün bir temsilini) geri almayı bekliyorum . Ben istiyorum 200ben aslında bir tane var demek durumu ve devam edip kullanabilirsiniz.

REST API'ler için, 400 ve 500 durum kodlarını istisnalar gibi bir şey olarak düşünüyorum. Aldığınız istek için ne zaman "normal" bir yanıt veremeyeceğinizi belirtmek için bunları kullanırsınız; böylece müşterinin almayı beklediği bilgileri işlemek yerine istisnai bir şey yapması gerekir.

Bu, bir API tüketicisi olarak, bir yanıt alan veya bir istisna atan bir tür işaretlenmiş geri arama işlevini kullanabileceğim anlamına gelir. Bu harika; benim normal mantığım düz bir kod olabilir ve hata kodumu yerel kodda yaptığım şekilde düzenleyebilirim. Beklenmeyen 404'ler, daha sonra { errorMessage: "Device 123 not found" }bir DeviceInfonesneymişim gibi işlem yaptığım zaman, "eksik öznitelik" hataları olarak değil, hiçbir şey yapmak zorunda kalmadan istisnalar "hiçbir kaynak bulunamadı" olarak tezahür edecek .

Son nokta olduğunu sen neden olursa http://example.com/restapi/deviceinfo edilir bulundu ve teklif sadece id=123o zaman ya a geri dönebilirler C fonksiyonları olarak arayüz problemlerinin aynısını ya oluştururken, değildir ve bu nedenle vücutta bir hata mesajı ile 200 dönmek olduğunu doğru sonucu veya bir hata kodunu veya rasgele döndürerek sorunları belirten yöntemleri doğrulayınnull. Arayüzünüzün bir kullanıcısı olarak, "ayrı" bir kanalda belirtilen hataların düzenli iadelerden gösterilmesi daha iyidir. Bu, HTTP 200, 404 ve 500 yanıtlarının düşük seviye bakış açısından aynı kanal olmasına rağmen, bu da geçerlidir. Standartlaştırılmış ve ayırt edilmeleri kolaydır, böylece REST istemci çerçevem ​​bu durumları kendi dilimdeki uygun yapılara dönüştürmek için kolayca açabilir; JSON katmanıyla aynı şeyi yapmak için (her zaman 200 deyin ve bana bir DeviceInfoveya bir hata mesajı verin) kullandığınız JSON şemaları hakkında biraz bilgi katmam gerekiyor.

Bu yüzden sadece 200, beklenen türden geçerli bir değer döndürebiliyorsanız kullanın (bu nedenle http://example.com/restapi/search-devices?colour=bluemavi cihaz yoksa boş bir dizi ile 200'ü döndürebilirsiniz; boş bir dizi geçerli bir dizidir ve talebe makul bir cevap "I tüm mavi cihazların detaylarını istiyorum "). Yapamazsanız, en uygun 200 olmayan durum kodunu kullanın. Her ne kadar "cihaz 123 mevcut değil", "cihaz 123'ün ayrıntılarını bana ver" e verilen doğru cevap olsa da ve sunucu için bir hata olmasa da , müşterinin geri alacağı DeviceInfove geri dönmesi beklentisi için bir istisnadır. normal olarak iletilmemeli "işte sorduğun şey bu" cevabı.

Bulunamayan 404'ten ayrılmak için 422 İşlenemeyen Varlık hatasını kullanabilirsiniz . 422, sunucunun isteği anladığı ancak uygun bir cevap veremediği anlamına gelir. Bu kodu benzer durumlarda kullanıyorum.

Hata 500 normal olarak isteğin bir sunucu tarafı programını düştüğünü gösterir; İşletme ortamlarında bu hatalar yüze yumurta olarak değerlendirilir ve önlenir.

Hata 4xx, programlayıcıya API uç noktasının (kaynak) bulunmadığını bildirmelidir. Sonuç olarak, uygun son noktaya ulaşıldığında, bu noktadan itibaren ele alınan herhangi bir hata, API'nin, 200 yanıtlı bir hata mesajı ile birlikte dikkatlice ele alınması gereken programcı sorumluluğudur.

W3, 404'ün başka bir cevap verilmediğinde kullanıldığını not etse de , bu bir 204 (İçerik Yok) yanıtı için iyi olmaz mıydı? İstek bir işleme açısından geçerliydi ve sunucu isteği işleme koydu ve bir sonucu oldu. Bu, 2xx yanıtlarına dayanan bir başarıdır. Bu özel istek için hiçbir içerik bulunmadığından, 204 kullanıcıya sorgularında yanlış bir şey olmadığını ancak orada hiçbir şey olmadığını söyler.

Ayrıca, 409 (Çatışma) uygun bir cevap olduğu için zayıf bir dava açabilirsiniz. 409 en sık bir POST için kullanılsa da

İstek, kaynağın mevcut durumu ile bir çakışma nedeniyle tamamlanamadı. Bu koda yalnızca kullanıcının anlaşmazlığı çözmesi ve isteği yeniden göndermesi beklenen durumlarda izin verilir. Yanıt organı, kullanıcının çatışmanın kaynağını tanıması için yeterli bilgiyi içermelidir. İdeal olarak, yanıt varlığı, sorunu çözmesi için kullanıcı veya kullanıcı aracısı için yeterli bilgiyi içerecektir; ancak, bu mümkün olmayabilir ve gerekli değildir.

Muhtemelen, istenen kimliğin bulunmaması buradaki ihtilaftır ve sistemde böyle bir kimliğin bulunmadığı mesajına geri dönerek kullanıcının bu çakışmayı tanıması ve çözmesi için yeterli bilgi olduğu söylenebilir.

Diğer cevaplar bunu örtbas ediyor, ancak sadece 500 serisi bir hatanın "batırdım" anlamına geldiğini belirtmek istedim. Bu durumda, "Ben" API anlamına gelir, bu yüzden işlenmemiş bir sunucu hatası veya benzeri. 400 serisi bir hata "sizi mahvetti" anlamına gelir - API'nin arayanı yanlış bir şey gönderdi.

Diğer kullanıcılar, kitaba gitmek istemeniz durumunda ne yapmaları gerektiğine dair geçerli cevaplar sağlamışlardır.

Bununla birlikte, RESTfullık hakkında çok fazla okumanızı ve bu konuda kesinlikle dolandırıcı olmanızı öneririm.

REST kaprisli bir protokoldür, çünkü kitabı kullanırken kitaptan geçmek istiyorsanız, hem müşteriyi hem de sunucuyu REST yoluyla iletişim kurduklarına dair özel bir bilgiye sahip olmak için inşa etmeye zorlar, bu nedenle özünde özel iletişim protokolü kullanılan soyutlanamaz.

Farklı bir yaklaşım var: tamamen RESTfulness'tan uzak durun ve onu sadece bir iletişim protokolü olarak kullanın ve başka bir şey kullanmayın. Bu, geri verilmesi gereken yanıtların yalnızca "HTTP 200 OK" ve "HTTP 500 Dahili Sunucu Hatası" olduğu anlamına gelir; çünkü iletişim protokolü söz konusu olduğunda, iletişim kurma girişiminin yalnızca iki sonucu olabilir: talep başarıyla sonuçlandı Sunucuya teslim edilir veya gönderilmez.

Teslimattan sonra olan, iletişim protokolünün işi değil. Bu nedenle, sunucu isteği başarıyla kabul edip işleme koymaya başladığında, birçok hata ortaya çıkabilir, ancak bunların tümü, iletişim protokolünün hakkında bir şey bilmesi gereken işlerden hiçbiri olmayan uygulamaya özgü hatalardır. İletişim protokolünün bildiği kadarıyla mükemmel bir şekilde görünen bir yanıtın yükü içinde iletilmelidirler.

Bu nedenle, sonuçta, "HTTP 200 OK" ve "geri dönüş yükü içerisinde (HTTP parlance" yanıt içeriği gövdesi ")" ID bulunamadı "ya da her neyse, uygulamaya özel bir hata kodunun dönmesini öneririm.