Bir API'dan JSON yanıtlarını yapılandırmak için standartlar veya en iyi uygulamalar var mı? Açıkçası, her uygulamanın verileri farklıdır, bu yüzden çok fazla ilgilenmiyorum, daha çok "yanıt levhası", eğer olacak. Ne demek istediğime bir örnek:

Başarılı istek:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Başarısız istek:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Evet, ortaya çıkan birkaç standart var (standart tanımında bazı özgürlükler olsa da):

1. JSON API - JSON API, yalnızca yanıtları değil kaynakları da oluşturmayı ve güncellemeyi kapsar.
2. JSend - Basit ve muhtemelen zaten yaptığınız şey.
3. OData JSON Protokolü - Çok karmaşık.
4. HAL - OData gibi ama HATEOAS gibi olmayı hedefliyor .

JSON API açıklama biçimleri de vardır:

• Çalım
  • JSON Şeması (swagger tarafından kullanılır, ancak tek başına kullanabilirsiniz)
• JSON'daki WADL
• Raml
• HAL çünkü teoride HATEOAS kendini tanımlamaktadır.

Google JSON kılavuzu

Başarılı yanıt dönüşü data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Hata yanıtı dönüşü error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

ve istemciniz JS if ("error" in response) {}ise, bir hata olup olmadığını kontrol etmek için kullanabilirsiniz .

Bir defacto standardı gerçekten ortaya çıkmadı (ve asla olmayabilir). Ama ne olursa olsun, işte benim almam:

Başarılı istek:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Başarısız istek:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Avantajı: Hem başarı hem de hata durumlarında aynı üst düzey öğeler

Dezavantaj: Hata kodu yok, ancak isterseniz durumu (başarılı veya başarısız) bir kod olarak değiştirebilirsiniz, -ya da- "kod" adlı başka bir üst düzey öğe ekleyebilirsiniz.

Sorunuzun REST web hizmetleri tasarımı ve daha doğrusu başarı / hata ile ilgili olduğunu varsayarsak.

3 farklı tasarım türü olduğunu düşünüyorum.

1. Kullan yalnızca HTTP Durum kodu bir hata olmadığını belirtmek ve standart olanlar (genellikle yeterli olacaktır) kendinizi sınırlamak için denemek için.

   • Artıları: API'nizden bağımsız bir standarttır.
   • Eksileri: Gerçekten ne olduğu hakkında daha az bilgi.

2. HTTP Status + json gövdesini kullanın (bir hata olsa bile). Hatalar için tek tip bir yapı tanımlayın (örn: kod, mesaj, neden, tür, vb.) Ve hatalar için kullanın, eğer bir başarı ise, beklenen json yanıtını döndürün.

   • Artıları: Mevcut HTTP durum kodlarını kullandığınızda ve hatayı açıklayan bir json döndürdüğünüzde hala standarttır (ne olduğu hakkında daha fazla bilgi sağlarsınız).
   • Eksileri: Çıkış json, bir hata veya başarı olup olmadığına bağlı olarak değişir.

3. Http durumunu unut (ör: her zaman durum 200) , her zaman json kullanın ve yanıtın köküne bir boolean responseValid ve bir hata ise doldurulacak bir hata nesnesi (kod, mesaj vb.) Ekleyin, aksi takdirde diğer alanlar (başarı) doldurulur.

   • Artıları: İstemci yalnızca bir json dizesi olan yanıt gövdesi ile ilgilenir ve durumu (?) Yoksayar.

   • Eksileri: Daha az standart.

Seçmek size kalmış :)

API'ye bağlı olarak 2 veya 3 seçerim (json rest apis için 2'yi tercih ederim). REST Api tasarımında deneyimlediğim başka bir şey, her kaynak (url) için belgelerin önemi: parametreler, gövde, yanıt, başlıklar vb + örnekler.

Jersey (jax-rs uygulaması) + genson (java / json databinding library) kullanmanızı da tavsiye ederim . Sadece sınıf yolunda genson + jersey düşürmeniz gerekir ve json otomatik olarak desteklenir.

DÜZENLE:

• Çözüm 2'nin uygulanması en zor olanıdır, ancak avantaj, sadece iş hatalarını değil, istisnaları da iyi bir şekilde ele alabilmenizdir, ilk çaba daha önemlidir, ancak uzun vadede kazanırsınız.

• Çözüm 3, hem sunucu tarafında hem de istemcide uygulanması kolaydır, ancak returnValid + hatasını da içeren bir yanıt nesnesine döndürmek istediğiniz nesneleri kapsüllemek zorunda kalacağınız kadar hoş değildir.

RFC 7807: Problem Detayları HTTP API'ler için şu anda biz resmi bir standarda sahip en yakın şeydir.

İnstagram kullanılan instagram biçimi

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

Bunun bir standart olduğunu iddia etmek kadar kibirli olmayacağım, bu yüzden "tercih ederim" formunu kullanacağım.

Ben kısa yanıt tercih (/ makale listesi talep ederken ben bir JSON makale dizisi istiyorum).

Tasarımlarımda durum raporu için HTTP kullanıyorum, 200 tanesi sadece yükü döndürüyor.

400 , istekte neyin yanlış olduğuna dair bir mesaj döndürür:

{"message" : "Missing parameter: 'param'"}

Dönüş 404Model / denetleyici / URI yoksa

Yanımda işlemede hata varsa, 501'i bir mesajla döndürürüm :

{"message" : "Could not connect to data store."}

Gördüğüm kadarıyla, birkaç REST-ish çerçevesi bu çizgiler boyunca olma eğilimindedir.

Gerekçe :

JSON'un bir yük biçimi olması gerekiyordu , bu bir oturum protokolü değil. Ayrıntılı session-ish yükleri fikri, XML / SOAP dünyasından ve bu şişirilmiş tasarımları oluşturan çeşitli yanlış yönlendirilmiş seçeneklerden gelir. Tüm bunların büyük bir baş ağrısı olduğunu fark ettikten sonra, REST / JSON'un tüm amacı onu ÖPMEK ve HTTP'ye bağlı kalmaktı. Ben ya JSend uzaktan standart bir şey olduğunu düşünmüyorum ve özellikle aralarında daha ayrıntılı değil. XHR HTTP yanıtına tepki verir, AJAX'ınız için jQuery kullanırsanız (çoğu gibi) hataları yakalamak için try/ catchve done()/ fail()geri aramaları kullanabilirsiniz. JSON'daki durum raporlarının ne kadar kapsülleyici olduğunu bundan daha yararlı göremiyorum.

Değeri için bunu farklı yapıyorum. Başarılı bir çağrıda sadece JSON nesneleri bulunur. Gerçek ve JSON nesnesi olan bir yük alanı gösteren bir başarı alanı içeren bir üst düzey JSON nesneye ihtiyacım yok. Sadece uygun JSON nesnesini 200 veya başlıktaki HTTP durumu için 200 aralığında uygun olanı döndürürüm.

Ancak, bir hata varsa (400 ailesinde bir şey) iyi biçimli bir JSON hata nesnesi döndürürüm. Örneğin, istemci bir e-posta adresi ve telefon numarası ile bir kullanıcı POSTing ve bunlardan biri hatalı (yani temel veritabanına ekleyemezsiniz) böyle bir şey döndürür:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

Buradaki önemli bitler, "field" özelliğinin, doğrulanamayan JSON alanıyla tam olarak eşleşmesi gerektiğidir. Bu, müşterilerin isteklerinde neyin yanlış gittiğini tam olarak bilmesini sağlar. Ayrıca, "ileti" isteğin yerel ayarında. Hem "emailAddress" hem de "phoneNumber" geçersizse, "error" dizisi her ikisi için de girişler içerir. Bir 409 (Çakışma) JSON yanıt gövdesi şöyle görünebilir:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

HTTP durum kodu ve bu JSON ile istemci, hatalara belirli bir şekilde yanıt vermek için ihtiyaç duydukları her şeye sahiptir ve HTTP durum kodlarını değiştirmeyi tamamlamaya çalışan yeni bir hata standardı oluşturmaz. Bunların yalnızca 400 hata aralığında gerçekleştiğini unutmayın. 200 serisindeki herhangi bir şey için uygun olan her şeyi döndürebilirim. Benim için genellikle HAL benzeri bir JSON nesnesidir, ancak bu gerçekten önemli değildir.

Eklemeyi düşündüğüm bir şey, "hatalar" dizi girişlerinde veya JSON nesnesinin kökünde sayısal bir hata koduydu. Ama şu ana kadar ihtiyacımız olmadı.

Google, Facebook, Twitter, Amazon ve diğerleri gibi büyük yazılım devlerinin geri kalan api yanıt formatları üzerinde herhangi bir anlaşma yoktur, ancak bazı kişilerin yanıt formatını standartlaştırmaya çalıştığı yukarıdaki cevaplarda birçok bağlantı sağlanmıştır.

API'lerin ihtiyaçları farklı olabileceğinden, herkesi işe almak ve bazı formatları kabul etmek çok zordur. API'nızı kullanan milyonlarca kullanıcınız varsa neden yanıt biçiminizi değiştiresiniz?

Google, Twitter, Amazon ve internetteki bazı yayınlardan esinlenerek yanıt biçimini almam aşağıdadır:

https://github.com/adnan-kamili/rest-api-response-format

Yağma dosyası:

https://github.com/adnan-kamili/swagger-sample-template

JSON'un amacı, tamamen dinamik ve esnek olmasıdır. İstediğiniz kaprise bükün, çünkü bu sadece tek bir düğüme dayanan bir dizi serileştirilmiş JavaScript nesnesi ve dizisidir.

Kök düğümün türü size bağlıdır, içerdiği şey size bağlıdır, yanıtla birlikte meta veri gönderip göndermediğiniz size bağlıdır, mime türünü ayarlayıp ayarlamamanıza application/jsonveya text/plainsize bağlı olarak ( kenar kasalarını nasıl kullanacağınızı bildiğiniz sürece).

Beğendiğiniz hafif bir şema oluşturun.
Şahsen, analitik izleme ve mp3 / ogg sunumu ile resim galerisi sunumu ve çevrimiçi oyun oynamak için metin mesajlaşma ve ağ paketlerinin ve blog yayınlarının ve blog yorumlarının hepsinin ne olduğu konusunda çok farklı gereksinimleri olduğunu buldum. gönderilen ve ne alınan ve nasıl tüketilmesi gerektiği.

Yani, istediğim son şey, her şeyi yaparken, her birini XML2.0 veya daha fazlasına dayanan aynı ortak standartlara uydurmaya çalışmaktır.

Bununla birlikte, size mantıklı ve iyi düşünülmüş şemaları kullanmak için söylenecek çok şey var .
Bazı API yanıtlarını okuyun, neyi sevdiğinizi not edin, neyi sevmediğinizi eleştirin, bu eleştirileri yazın ve sizi neden yanlış şekilde ovuşturduklarını anlayın ve sonra öğrendiklerinizi ihtiyacınız olana nasıl uygulayacağınızı düşünün.

JSON-RPC 2.0 standart bir istek ve yanıt formatı tanımlar ve REST API'leriyle çalıştıktan sonra taze bir soluk alır.

Daha sonra gelenler için, HAL, JSend ve JSON API'yi içeren kabul edilen cevaba ek olarak, incelemeye değer birkaç özellik daha ekleyeceğim:

• W3C Önerisi olan ve JSON'da birlikte çalışabilir Web Hizmetlerinin nasıl oluşturulacağını belirten JSON-LD
• " REST için basit ve sezgisel JSON tabanlı bir hipermedia türü" olduğunu iddia eden REST için Ion Hiper Ortam Türü

Önerilen temel çerçeve iyi görünüyor, ancak tanımlandığı gibi hata nesnesi çok sınırlı. Sorunu ifade etmek için çoğu zaman tek bir değer kullanılamaz ve bunun yerine bir problemler ve nedenler zincirine ihtiyaç vardır .

Biraz araştırma yaptım ve hata (istisnalar) döndürmek için en yaygın biçimin bu formun bir yapısı olduğunu buldum:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Bu, OASIS veri standardı OASIS OData tarafından önerilen formattır ve orada en standart seçenek gibi görünmektedir, ancak bu noktada herhangi bir standardın yüksek benimsenme oranları yoktur. Bu biçim JSON-RPC belirtimiyle tutarlıdır.

Bunu uygulayan tüm açık kaynak kütüphanesini şu adreste bulabilirsiniz: Mendocino JSON Utilities . Bu kütüphane istisnaların yanı sıra JSON Nesnelerini de destekler.

Ayrıntılar JSON REST API'sindeki Hata İşleme hakkındaki blog yayınımda tartışıldı

Sağduyunun dışında yasalara aykırı veya kanun kaçağı standardı yoktur. Bunu iki kişi gibi soyutlaştırırsak, standart birbirlerini en az zamanda en az zamanda doğru bir şekilde anlamaları için en iyi yoldur. Bizim durumumuzda, 'minimum sözcükler', bant genişliğini taşıma verimliliği için optimize etmektedir ve 'doğru bir şekilde anlamak' ayrıştırıcı verimliliğinin yapısıdır; sonuçta daha az veri ve ortak yapı ile sonuçlanır; böylece bir pim deliğinden geçebilir ve ortak bir kapsamdan (en azından başlangıçta) ayrıştırılabilir.

Neredeyse önerilen her durumda, 'Başarı' ve 'Hata' senaryosu için ayrı bir yanıt görüyorum ki bu benim için bir belirsizlik. Bu iki durumda yanıtlar farklıysa, o zaman neden gerçekten bir 'Başarı' bayrağı koymamız gerekiyor? 'Hata'nın yokluğunun' Başarı 'olduğu belli değil mi? 'Başarının' bir 'Hata' seti ile DOĞRU olduğu durumlarda yanıt almak mümkün müdür? Veya 'Hata' ayarlanmadığında 'Başarı' YANLIŞ mı? Sadece bir bayrak yeterli değil mi? Sadece 'Hata' bayrağı almayı tercih ederim, çünkü 'Başarı'dan daha az' Hata 'olacağına inanıyorum.

Ayrıca, gerçekten 'Hata' işaretini yapmalı mıyız? Birden fazla doğrulama hatasıyla yanıt vermek istersem ne olur? Bu nedenle, bu düğüme alt öğe olarak her hata ile bir 'Hata' düğümü olmasını daha verimli buluyorum; burada boş (sıfıra kadar sayar) bir 'Hata' düğümü 'Başarılı' anlamına gelir.

Mobil geliştiriciler tarafından kolayca anlayabilen web apis için En İyi Yanıt.

Bu "Başarı" Yanıtıdır

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Bu "Hata" Yanıtıdır

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}