Cara mewakili (enum) jenis dalam API publik

32

Saya sedang mengerjakan API sederhana yang ingin saya gunakan untuk klien saya sendiri, dan untuk dibuka untuk umum di masa depan. Saya memiliki objek "Item" yang dapat memiliki "tipe" yang berbeda. Jenisnya adalah C "typedef enum", untuk saat ini saya punya:

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

(Saya dapat menambahkan beberapa di masa depan)

Saya bertanya-tanya apakah saya lebih suka mentransfernya sebagai integer atau didefinisikan sebagai "string". JSON akan menjadi:

Untuk bilangan bulat:

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

Untuk string:

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

Saya bertanya-tanya apakah ada praktik terbaik untuk ini. Menjaga bilangan bulat akan sedikit menyederhanakan kode, dan mengurangi bandwidth, tetapi string akan lebih mudah diingat oleh pengembang. Saya ingat saya bekerja pada sebuah proyek, dan saya harus ingat 1 = gambar, 2 = audio, 3 = html, ... yang tidak masuk akal.

Jadi saya bertanya kepada Anda, jika Anda tahu aspek lain yang harus saya pertimbangkan.

api patterns-and-practices enum

— Julien
sumber

Apakah Anda mengharapkan pengguna untuk mengedit JSON secara manual sesering mungkin?

— James

39

Berikan string. Angka tidak ada artinya. Anda tidak menggunakannya dalam kode Anda sendiri, kan (Anda membungkus nilai enum sekitar, yang pada dasarnya adalah string) - mengapa menghukum pengguna karena harus menggunakan angka-angka ini?

Satu-satunya pro jika Anda mengekspos angka - lebih mudah bagi Anda untuk menguraikannya. Tapi hei, siapa yang peduli padamu. Jaga klien API.

Jika Anda memberikan string - lebih mudah bagi klien; tidak akan pernah harus mengatakan hal-hal seperti "4 telah ditinggalkan demi 17"; parsing sedikit lebih sulit atas nama Anda, tapi itu bagus.

Jangan berikan keduanya: sebagai pengguna, saya bertanya-tanya

mana yang harus saya gunakan? Kedua? [untuk membaca dokumen]
mengapa ada dua cara untuk mengatakan hal yang sama? apakah mereka sedikit berbeda? [untuk membaca dokumen]
bagaimana jika saya menentukan keduanya dan ada ketidakcocokan? apakah itu akan mengeluh? akankah seseorang diutamakan? yang mana? [untuk membaca dokumen]

Seperti yang Anda lihat, Anda membuat saya membaca banyak dokumen tanpa alasan.

— iluxa
sumber

Saya setuju dengan @iluxa

— portforwardpodcast

1

Bagaimana jika enum adalah anggota kelas (objek) yang diharapkan sebagai input dalam panggilan istirahat?

— Stallion

2

String.

Salah satu kekuatan Json adalah sifatnya yang dapat dibaca manusia. Ketika men-debug output setengah tahun dari sekarang "0" tidak akan memberi tahu Anda apa-apa.

Beberapa kerangka kerja akan melakukan konversi otomatis juga. Jika Anda tidak menggunakannya - Anda dapat membuat konverter sendiri untuk menjaga kode Anda tetap kering.

Ini berubah dalam pemilihan suara.

— Evgeni
sumber

1

Praktik Terbaik tergantung pada siapa yang mengonsumsi API Anda. Jika Anda mencoba membuat hidup lebih mudah bagi konsumen, Anda harus memberikan kode sampel dalam C, JAVA, iOS, python, ruby yang dapat mengkonsumsi api Anda. Dalam pembungkus ini, Anda dapat memasukkan enum, gunakan int di json, dan kemudian parsing json Anda ke sebuah objek dengan enum yang telah ditetapkan, dan kembalikan objek ini ke kode pengguna.

Hal lain yang bisa Anda lakukan adalah menyediakan keduanya. contohnya:

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

Atau Anda dapat menggunakan tipe, dan tipeStr tergantung pada apa yang terlihat terbaik untuk api Anda.

Dan kemudian jelaskan dalam dokumentasi Anda bahwa ini berlebihan dan terserah pengembang untuk memilih mana yang terbaik untuk aplikasi mereka.

Lihatlah json di sini: https://dev.twitter.com/docs/api/1/get/search Twitter memiliki contoh memberikan data yang berlebihan (id dan id_str), tetapi ini karena beberapa klien json tidak dapat menguraikan int panjang dari "angka" di json dan membutuhkan string untuk menghindari kehilangan digit

— portforwardpodcast
sumber