Bir HTTP API her zaman bir gövde döndürmeli mi?

HTTP API yanıtlarıyla ilgili bir tür standart var mı?

Bu konuyu okuduktan sonra merak etmeye başladım. Çalışmamda genel HTTP JSON API'mizi geliştiriyoruz ve kesinlikle gerekmediğinde hiçbir şey döndürmüyoruz (örneğin / PUT / resource / {id} 'a yalnızca OK veya karşılık gelen 4XX veya 5XX kodu girdiğinde 200 döndürür, ancak JSON gövdesi)

{"success":true}Yukarıdaki bağlantıda tartışıldığı gibi bir jenerik döndürmeli miyiz , yoksa "boş" bir cismi iade edip her şeyi http yanıt kodlarıyla ele almamız uygun mu?

PUT ile ilgili olarak, ancak POST için de geçerlidir. HTTP şartname bunu açıklayan olduğu senaryo geldiğinde bölüm 9 kural ve hatta tavsiye (OLMALI) biraz boş. Sorunuzla ilgili satır en yakından kapsanmaktadır:

Yeni bir kaynak oluşturulursa, kaynak sunucu, kullanıcı aracısını 201 (Oluşturulan) yanıtı üzerinden bilgilendirmelidir. Mevcut bir kaynak değiştirilirse, isteğin başarılı bir şekilde tamamlandığını belirtmek için 200 (OK) veya 204 (İçerik Yok) yanıt kodları gönderilmelidir.

Bunun üzerinde herhangi bir uykuyu kaybedeceğimi sanmıyorum, ama soruyorum, cevabına JSON parçası ekleyerek ne kazanıyorsunuz? Az önce çıktınız (Tamam, çok fazla olabilir!) Yanıt, durum kodunun size söylediği şekilde daha az doğru bir şekilde yinelenerek yanıt veriyor. PUT'unuz yeni bir nesne dönüşü 201 ile sonuçlandıysa (PUT'un amacı gibi), eğer bir nesne güncellendiyse 204.

Bu arada, API bir yana, 200 yerine, hiçbir şey döndürmezseniz 204 kullanın.

Bir dizi RESTful arayüzü geliştirdiğinizi varsayarsak, hiçbir standart yoktur, bu nedenle ne yaparsanız yapın, iyi bir şekilde belgeleyin, örnekler verin ve her şey yoluna girecek.

Temel HTTP standardı, yanıtla döndürülen bir belge olmasını zorunlu kılmaz. Ekonominin uğruna, bir HTTP durumu gerekli olan her şeyi taşıdığında, vücut israf olur. Ancak, yeni kurallar ekleyen HTTP'nin üzerine inşa edilmiş standartlar vardır.

Belirleyen açık bir JSON API standardı vardır:

• Bir JSON nesnesi , her JSON API yanıt belgesinin kökeninde OLMALIDIR . (italik, metni netleştirmek için eklediklerimi temsil eder)

Ne yazık ki, standart boş bir belgenin nasıl temsil edileceğini belirtmemektedir ve devam eden bir çalışmadır. En iyi ihtimalle bir rehber olarak kullanırdım.

Bazı uygulamalar ( ElasticSearch gibi ) tam bir JSON api sağlar ve her zaman bazı meta verilere sahiptir, böylece sunucunun verilerinizi nasıl yönettiği hakkında daha iyi bir fikir edinebilirsiniz. Standart yanıt nesnesi, istek bir hatayla sonuçlandıysa, kaç tane düğümün etkilendiğini vb. Gösterir. ElasticSearch, mime türü için "application / json" kullanır. jsonapi.org standardı.

JQuery ve benzeri Javascript çerçeveleri her zaman bir belge olacağını varsayar. Soru, API tüketicilerinize ne kadar hata kontrolü yaptırmak istiyorsunuz? Yalnızca istek türüne bağlı olarak uzatılan tüm yanıtlar için standart bir biçim bulursanız, iade belgesine olan gereksinimi karşılarsınız ve API tüketicileriniz için daha kolay hata ayıklamayı kolaylaştırırsınız.

Hayır , örneğin, 204 cevap için mesaj gövdesi içermemeliyiz. {success | status | isSuccessful: true} gereksizdir.

Uygulamada (veya daha sonraki jquery sürümlerinde söylemeliyim), uygulama / json içerik türü için boş yanıt hata verir. Uygulama / json olduğu için geçerli bir json gövdesine sahip olması gerektiği argümanı anlıyorum. Bu nedenle, uygulama / json içerik türü için boş yanıt geçerli json olan 'null' veya '{}' olacaktır.

Boş yanıtlar için uygulama / json döndürmeyen, jquery için çalışması gereken başka bir yol var. Sadece text / plain veya başka bir şey kullanın ve müşterinin bu tiple başa çıkabildiğinden emin olun.

Not 204'ü yalnızca açıkça geri dönen ileti gövdesi için yasakladığımı hatırlayabilirim. Bulduğumuz şey, her zaman 204 kullanamayacağımızdır. Sorun, 204 yanıt için MSIE düşürme yanıtı başlığıdır , bu nedenle kötü olan hiçbir içerik ve başlık yoktur . Birçoğu MSIE kullandığından, bunu 200 statüsüne değiştirmek zorunda kaldık.

Hayır, ancak kodunuzun tutarlılığı için yardımcı olacaktır. Aynı zamanda hata ayıklama amaçları için iyi. Aynı zamanda web sitesinin bakımında da büyük bir yardımcı olacaktır. Bunu hatırlayın: Hata kodu makine içindir, hata mesajı insan içindir. Bu yüzden bir yanıt gövdesi kullanmanızı öneriyorum. Her neyse, olumsuz etkisi, faydalarına kıyasla yalnızca minimum düzeyde (ağ üzerinden gönderilen birkaç bayt). Başka bir şey, gerektiğinde bir mesaj metni yazmayı unutmanızı da önleyecektir.

Yanıtta basit bir başarı durumu döndürmezdim, http hata kodu yalnızca başarı veya hatayı gösterir. Uygulamaya özel hata kodları veya hata mesajları gibi ayrıntılı hata bilgileri eklemek için yalnızca yanıtın kendisini kullanmayı dahil ederim.

PUT, PATCH ve POST istekleri için genellikle durumu döndürürsünüz, istek uygulandıktan sonra, kaynağın durumunu verir, boş bir cevap değil.

Basitçe bir kaynak oluşturmak yerine bir eylemi temsil eden POST istekleri için (çok RESTful değil, ancak pratikte yine de kullanışlı), geri döndürecek yararlı verileri olmayan, yani boş bir json nesnesinden oluşan bir yanıt döndürürdüm {}. Bu şekilde müşteri geçerli bir yanıt alır ve daha sonra bazı bilgiler eklemek, onu kırmak için olası değildir.

DELETE istekleri için 204 döndürür ve boş bir gövde oldukça yaygındır, bu kaynak daha sonra bulunmadığından mantıklıdır.

Sadece gerekli olanı + küçük bir açıklama getirmeyi öneriyorum.

Örneğin, API'nizin nasıl kullanılacağına bağlı olarak, kaydedildikten sonra olduğu gibi nesnenin bir kopyasını ekleyebilirsiniz.

Öyleyse, {key: 123} POST değeri {key: 123, foo: 'bar'} ile dönebilir.

Temel fikir, nesneyi geri döndürmek ve daha sonra tekrar sorgulamak zorunda kalmaktır.

Bununla birlikte, API tüketicileriniz için geri göndermeye gerek olmayan nesneye ihtiyaç yoktur.

POST PUT ve PATCH için hiçbir nesne gerekmediğinde genellikle alma işlemini kolaylaştırır, çünkü {success: true} veya bazılarını döndürürüm. Bununla birlikte, nesnenin kaydedilmiş temsilini geri döndürme zamanının% 99'unun daha iyi olması, yine de ihtiyaç duymamaları nadirdir ve hepsini bir istekte sonra ikiye göndermek "ucuz" olur.

Spesifik olarak, bir laboratuvarda her şeyi sadece durum kodları ile halletmek mükemmel bir şekilde bulunur, gerçek dünyada, gereksiz olsa bile, bazı verileri iade etmek daha iyidir, böylece API tüketicileri söylemeye çalıştığınız şeyi kolayca elde edebilir.

200 döndürerek {success: true} insanların her iki yönde de kod yazmasını sağlar:

if response.code == 200
  do stuff
end

ve

if response.body.success
  do stuff
end

ek olarak, senin tarafında yapmak o kadar da zor değil.

Son olarak, (kakaların cevap yapısı için özür dilerim), halka açık bir JSON API sağlayarak, nasıl kullanılacağına dair çok fazla kontrol bırakmayı bıraktınız. Bazı müşteriler farklı kuruluşlara (veya orada bulunmayanlara) veya durum kodlarına farklı tepki gösterebilir.