REST API hata dönüşü iyi uygulamaları [kapalı]

Bir REST API hata döndürmek söz konusu olduğunda iyi uygulamalar hakkında rehberlik arıyorum. Ben şu anda herhangi bir yön alabilir böylece yeni bir API üzerinde çalışıyorum. İçerik türüm şu anda XML, ancak gelecekte JSON'u desteklemeyi planlıyorum.

Şimdi, örneğin bir istemci yeni bir kaynak eklemeye çalışır ancak depolama kotasını aşmış gibi bazı hata durumları ekliyorum. HTTP durum kodlarıyla (kimlik doğrulama için 401, yetkilendirme için 403 ve düz hatalı istek URI'ları için 404) belirli hata durumlarını zaten ele alıyorum. Mübarek HTTP hata kodlarına baktım ama 400-417 aralığının hiçbiri uygulamaya özgü hataları bildirmek için doğru görünmüyor. Bu yüzden ilk başta 200 OK ve belirli bir XML yükü ile uygulama hatamı döndürmek cazip geldi (yani. Bize daha fazla ödeme yapın ve ihtiyacınız olan depolamayı alacaksınız!) Ama düşünmeyi bıraktım ve sabunlu görünüyor (/ / korku içinde omuz silkme). Yanı sıra bazı http durum kodu tahrik ve diğer içerik tahrik gibi hata yanıtları ayrı durumlarda bölünmüş gibi geliyor.

Peki endüstri önerileri nedir? İyi uygulamalar (lütfen nedenini açıklayın!) Ve ayrıca bir müşteri pov'sinden, REST API'sinde ne tür bir hata işleme, istemci kodu için hayatı kolaylaştırır?

Bu yüzden ilk başta 200 OK ve belirli bir XML yükü ile uygulama hatamı döndürmek cazip geldi (yani. Bize daha fazla ödeme yapın ve ihtiyacınız olan depolamayı alacaksınız!) Ama düşünmeyi bıraktım ve sabunlu görünüyor (/ / korku içinde omuz silkme).

Gerçekten isteği ile yanlış bir şey olmadığı sürece 200 dönmek olmaz. Gönderen RFC2616 , 200 araç "isteği başarılı oldu."

Müşterinin depolama kotası aşılmışsa (herhangi bir nedenle), bir 403 (Yasak) döndürürdüm:

Sunucu isteği anladı, ancak yerine getirmeyi reddediyor. Yetkilendirme yardımcı olmaz ve istek tekrarlanmamalıdır. İstek yöntemi HEAD değilse ve sunucu, isteğin neden yerine getirilmediğini halka duyurmak istiyorsa, kuruluştaki ret nedenini açıklamalıdır. Sunucu bu bilgileri istemcinin kullanımına sunmak istemiyorsa, bunun yerine 404 (Bulunamadı) durum kodu kullanılabilir.

Bu, istemciye isteğin iyi olduğunu, ancak başarısız olduğunu (200'ün yapmadığı bir şey) bildirir. Bu aynı zamanda size yanıt organındaki sorunu (ve çözümünü) açıklama fırsatı verir.

Aklınızda başka hangi özel hata durumları vardı?

API'niz için doğru HTTP hata kodunu seçmek için harika bir kaynak: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Makaleden bir alıntı:

Nereden başlamalı:

2XX / 3XX:

4XX:

5XX:

Ana seçim, HTTP durum kodunu REST API'nizin bir parçası olarak ele almak isteyip istemediğinizdir.

Her iki yol da iyi çalışıyor. Kesinlikle konuşmak gerekirse, REST'in fikirlerinden birinin HTTP Durum kodunu API'nizin bir parçası olarak kullanmanız gerektiğine katılıyorum (başarılı bir işlem için 200 veya 201 ve çeşitli hata durumlarına bağlı olarak 4xx veya 5xx döndürün). , REST polisi yok. Ne istersen yapabilirsin. Çok daha berbat olmayan REST olmayan API'lerin "RESTful" olarak adlandırıldığını gördüm.

Bu noktada (Ağustos 2015) HTTP Durum kodunu API'nızın bir parçası olarak kullanmanızı öneririm. Çerçeveleri kullanırken dönüş kodunu görmek geçmişte olduğundan çok daha kolay. Özellikle, 200 olmayan geri dönüş vakasını ve 200 olmayan yanıtların gövdesini geçmişte olduğundan daha kolaydır.

HTTP Durum kodu, API'nizin bir parçasıdır

1. Hata koşullarınıza uyan 4xx kodlarını dikkatlice seçmeniz gerekecektir. Yük olarak alt kod ve açıklayıcı bir yorum içeren bir rest, xml veya düz metin mesajı ekleyebilirsiniz.

2. İstemcilerin HTTP düzeyindeki durum koduna erişmelerini sağlayan bir yazılım çerçevesi kullanmaları gerekir. Genellikle yapılabilir, her zaman kolay değildir.

3. İstemciler, bir iletişim hatasını gösteren HTTP durum kodları ile uygulama düzeyindeki bir sorunu belirten kendi durum kodlarınızı birbirinden ayırmak zorunda kalacaklardır.

HTTP Durum kodu API'nizin bir parçası DEĞİLDİR

1. Uygulamanız isteği alıp yanıt verdiğinde HTTP durum kodu her zaman 200 olur (hem başarı hem de hata vakaları)

2. TÜM yanıtlarınız "zarf" veya "başlık" bilgilerini içermelidir. Genellikle şöyle bir şey:

   zarf_ver: 1.0
   status: # istediğiniz kodları kullanın. Başarı için bir kod ayırın.
   msg: "ok" # Kodu yansıtan bir insan dizesi. Hata ayıklama için kullanışlıdır.
   data: ... # Varsa yanıtın verileri.

3. Yanıt durumu her zaman aynı yerde olduğundan (alt kod gerekmez), kodlarda sınırlama olmadığından, HTTP düzeyi durum kodunu getirmeye gerek olmadığından, bu yöntem istemciler için daha kolay olabilir.

İşte benzer bir fikri olan bir yazı: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Ana konular:

1. Daha sonra gerekirse API'nin anlambilimini değiştirmek için sürüm numaralarını eklediğinizden emin olun.

2. Belge ...

HTTP / 1.1 RFC'lerde tanımlananlardan daha fazla durum kodu olduğunu unutmayın, IANA kayıt defteri http://www.iana.org/assignments/http-status-codes adresindedir . Bahsettiğiniz durumda 507 durum kodu doğru geliyor.

Diğerlerinin işaret ettiği gibi, bir hata kodunda bir yanıt varlığına sahip olmak mükemmel bir şekilde izin verilir.

5xx hatalarının sunucu tarafı olduğunu unutmayın; diğer bir deyişle, istemci isteği geçmek için isteğine hiçbir şey değiştiremez. İstemcinin kotası aşılırsa, bu kesinlikle bir sunucu hatası değildir, bu nedenle 5xx'den kaçınılmalıdır.

İki tür hata vardır. Uygulama hataları ve HTTP hataları. HTTP hataları, AJAX işleyicinize işlerin iyi gittiğini ve başka bir şey için kullanılmaması gerektiğini bildirmek içindir.

5xx Server hatası

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Başarı

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Ancak, uygulama hatalarınızı nasıl tasarladığınız gerçekten size kalmış. Örneğin Yığın Taşması response, datave messageözellikleri olan bir nesne gönderir . İnandığım yanıt , işlemin başarılı olup olmadığını (genellikle yazma işlemleri için) içeriyor trueveya falsebelirtiyor. Veri (genellikle okuma işlemleri için) yükünü içerir ve mesaj (örneğin, hata mesajları gibi herhangi bir ek meta ya da yararlı mesajları içerir responseolan false).

Bunun partiye son derece geç olduğunu biliyorum, ancak şimdi 2013 yılında, yaygın dağıtılmış (RESTful) bir tarzda hata işlemeyi kapsayan birkaç medya türümüz var. Bkz. "Vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) ve "HTTP API'ları için Sorun Ayrıntıları", application / problem + json ( https: // tools). ietf.org/html/draft-nottingham-http-problem-05 ).

Kabul. REST'in temel felsefesi web altyapısını kullanmaktır. HTTP Durum kodları, tarafların HTTP yükünü artırmadan birbirleriyle iletişim kurmalarını sağlayan mesajlaşma çerçevesidir. Yanıt durumunu zaten ileten evrensel kodlar oluşturulmuşlardır ve bu nedenle, gerçekten RESTful olmak için, uygulamaların yanıt durumunu iletmek için bu çerçeveyi kullanmaları gerekir.

HTTP 200 zarfında bir hata yanıtı göndermek yanıltıcıdır ve istemciyi (api tüketicisi) büyük olasılıkla standart olmayan veya tescilli bir şekilde iletiyi ayrıştırmaya zorlar. Bu da verimli değildir; müşterilerinizi "gerçek" yanıt durumunu anlamak için her seferinde HTTP yükünü ayrıştırmaya zorlayacaksınız. Bu işlemeyi artırır, gecikme ekler ve istemcinin hata yapması için bir ortam oluşturur.

API'nizi mevcut 'en iyi uygulamalar' üzerine modellemek ilerlemenin bir yolu olabilir. Örneğin, Twitter hata kodlarını şu şekilde işler https://developer.twitter.com/en/docs/basics/response-codes

Lütfen protokol semantiğine sadık kalın. Başarılı yanıtlar için 2xx ve hata yanıtları için 4xx, 5xx kullanın - işinizdeki istisnalar veya diğerleri. Protokolde amaçlanan kullanım durumunda herhangi bir yanıt için 2xx kullanmış olsaydı, ilk etapta başka durum kodları olmazdı.

Uygulama hataları için 5xx hatalarını da unutmayın.

Bu durumda ne hakkında 409 (Çatışma)? Bu, kullanıcının depolanan kaynakları silerek sorunu çözebileceğini varsayar.

Aksi takdirde 507 (tamamen standart değil) de işe yarayabilir. Genel olarak hatalar için 200 kullanmazsanız 200 kullanmazdım.

İstemci kotası aşılırsa bu bir sunucu hatasıdır, bu durumda 5xx kullanmaktan kaçının.