Genel bir API'de türler nasıl temsil edilir?

32

Kendi müşterim için kullanmak ve gelecekte halka açmak istediğim basit bir API üzerinde çalışıyorum. Farklı "türleri" olabilecek "Öğe" nesnelerim var. Bu tip bir C "typedef enum" türü:

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

(Gelecekte bazılarını ekleyebilirim)

Merak ediyorum tamsayı olarak mı yoksa "dizge" olarak mı tanımlamalıyım? JSON şöyle olurdu:

Tamsayılar için:

{
  "name": "The name",
  "type": 0,
   ...
}

Dizeler için:

{
  "name": "The name"
  "type": "boolean"
   ...
}

Bunun için en iyi uygulama olup olmadığını merak ediyorum. Tamsayıyı tutmak kodu biraz basitleştirir ve bant genişliğini azaltır, ancak dizgelerin geliştiricilerin hatırlaması kolaylaşır. Bir proje üzerinde çalıştığımı hatırlıyorum ve 1 = image, 2 = audio, 3 = html, ... hatırlamak zorunda kaldım, bu da gerçek bir anlam ifade etmiyor.

Bu yüzden size soruyorum, başka bir yönden haberi varsa düşünmeliyim.

api patterns-and-practices enum

— Julien
kaynak

Kullanıcılarınızın JSON’yu elle sık sık düzenlemesini bekliyor musunuz?

— James

39

Dizeleri sağlayın. Sayılar anlamsız. Bunları kendi kodunuzda kullanmazsınız, doğru (enum değerlerini etrafına sayarsınız, bunlar temel olarak dizelerdir) - neden bu numaraları kullanmak zorunda bıraktığı için kullanıcıyı cezalandırıyorsunuz?

Sayıları ortaya çıkarırsanız sadece profesyonel - bunları ayrıştırmanız daha kolay. Ama hey, seni kim önemsiyor? API istemcilerine iyi bakın.

Dizeleri sağlarsanız - müşteriler için daha kolay; "4, 17 lehine itiraz edildi" gibi şeyler söylemek zorunda kalmayacak; sizin adınıza ayrıştırmak biraz zor, ama sorun değil.

İkisini de sağlama: Bir kullanıcı olarak merak ettim

hangisini kullanıyorum Her ikisi de? [dokümanlar okumaya]
Neden aynı şeyi söylemenin iki yolu var? incelikle farklı mılar? [dokümanlar okumaya]
ikisini de belirtirsem ve bir uyuşmazlık varsa? şikayet edecek mi biri öncelikli olur mu? hangisi? [dokümanlar okumaya]

Gördüğün gibi, sebepsiz yere beni çok fazla doktor okutuyorsun.

— iluxa
kaynak

@İluxa ile aynı fikirdeyim

— portforwardpodcast

1

Enum istirahat çağrısında girdi olarak sınıfın (nesne) üyesi bekleniyorsa?

— aygır

2

Teller.

Jackson'ın güçlü yönlerinden biri, insan tarafından okunabilir olmasıdır. Çıktının ayıklaması sırasında yarım yıl sonra “0” size hiçbir şey söylemez.

Bazı çerçeveler de otomatik dönüşüm yapacaktır. Kullanmıyorsanız - kodunuzu kuru tutmak için kendiniz bir dönüştürücü oluşturabilirsiniz.

Bu olsa, oylamada bir oylama olur.

— Evgeni
kaynak

1

En İyi Uygulama, API'nizi kimin kullandığına bağlıdır. Tüketici için hayatı kolaylaştırmaya çalışıyorsanız, api'nizi tüketebilecek C, JAVA, iOS, python, ruby'de örnek kod vermelisiniz. Bu paketleyicilere enum ekleyebilir, json'da bir int kullanabilir ve ardından json'unuzu enum ayarlanmış bir nesneye ayrıştırır ve bu nesneyi kullanıcı koduna geri döndürürsünüz.

Yapabileceğiniz başka bir şey, her ikisini de sağlamaktır. Örneğin:

{
  "name": "The name",
  "typeId": 0,
  "type": "ItemTypeBool"
   ...
}

Veya, api'niz için neyin iyi olduğuna bağlı olarak type ve typeStr komutlarını kullanabilirsiniz.

Ve daha sonra, dokümantasyonunuzda bunların gereksiz olduğunu ve uygulama için hangisinin daha iyi olacağını seçmek geliştiriciye kaldığını açıkça belirtin.

Buradaki json'a bakın: https://dev.twitter.com/docs/api/1/get/search Twitter, gereksiz veriler sağlama konusunda bir örneğe sahiptir (id ve id_str); json'da bir "sayı" dır ve hanelerin kaybolmasını önlemek için bir dize gerektirir

— portforwardpodcast
kaynak