Cách thể hiện (enum) các loại trong API công khai

32

Tôi đang làm việc trên một API đơn giản mà tôi muốn sử dụng cho khách hàng của riêng mình và để mở cho công chúng trong tương lai. Tôi có các đối tượng "Mục" có thể có các "loại" khác nhau. Loại này là C "typedef enum", hiện tại tôi có:

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

(Tôi có thể thêm một số trong tương lai)

Tôi tự hỏi liệu tôi nên chuyển nó dưới dạng số nguyên hay "chuỗi" được xác định. JSON sẽ là:

Đối với số nguyên:

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

Đối với chuỗi:

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

Tôi tự hỏi nếu có một thực hành tốt nhất cho việc này. Giữ số nguyên sẽ đơn giản hóa một chút mã và giảm băng thông, nhưng các chuỗi sẽ dễ nhớ hơn cho các nhà phát triển. Tôi nhớ tôi đã làm việc trong một dự án và tôi phải nhớ 1 = hình ảnh, 2 = âm thanh, 3 = html, ... điều đó không có ý nghĩa thực sự.

Vì vậy, tôi đang hỏi bạn, nếu bạn biết bất kỳ khía cạnh nào khác tôi nên xem xét.

api patterns-and-practices enum

— Julien
nguồn

Bạn có mong đợi người dùng của mình chỉnh sửa JSON theo cách thủ công thường xuyên không?

— James

39

Cung cấp các chuỗi. Con số là vô nghĩa. Bạn không sử dụng chúng trong mã của riêng mình, đúng (bạn đang bao bọc các giá trị enum, về cơ bản là các chuỗi) - tại sao lại phạt người dùng khi phải sử dụng các số này?

Các pro duy nhất nếu bạn làm lộ ra những con số - dễ dàng hơn để bạn phân tích chúng. Nhưng này, ai quan tâm đến bạn. Chăm sóc các khách hàng API.

Nếu bạn cung cấp các chuỗi - dễ dàng hơn cho khách hàng; sẽ không bao giờ phải nói những điều như "4 đã bị từ chối ủng hộ 17"; phân tích cú pháp khó hơn một chút thay cho bạn, nhưng điều đó tốt.

Không cung cấp cả hai: với tư cách là người dùng, tôi sẽ tự hỏi

Tôi dùng cái nào? Cả hai? [để đọc tài liệu]
Tại sao có hai cách để nói cùng một điều? chúng có khác nhau không? [để đọc tài liệu]
Điều gì xảy ra nếu tôi chỉ định cả hai và có sự không phù hợp? nó sẽ phàn nàn chứ? một sẽ được ưu tiên? cái nào? [để đọc tài liệu]

Như bạn có thể thấy, bạn đang cho tôi đọc rất nhiều tài liệu mà không có lý do.

— iluxa
nguồn

Tôi đồng ý với @iluxa

— portforwardpodcast

1

Điều gì xảy ra nếu enum là thành viên của lớp (đối tượng) được dự kiến là đầu vào trong phần còn lại gọi?

— ngựa giống

2

Dây.

Một trong những điểm mạnh của Json là nó có thể đọc được. Khi gỡ lỗi đầu ra nửa năm kể từ bây giờ "0" sẽ không cho bạn biết gì.

Một số khung cũng sẽ tự động chuyển đổi. Nếu bạn không sử dụng một - bạn có thể tự tạo một trình chuyển đổi để giữ cho mã của mình khô ráo.

Điều này lần lượt trong một cuộc bỏ phiếu, mặc dù.

— Evgeni
nguồn

1

Thực hành tốt nhất phụ thuộc vào người tiêu thụ API của bạn. Nếu bạn đang cố gắng làm cho cuộc sống của người tiêu dùng trở nên dễ dàng, bạn nên cung cấp mã mẫu bằng C, JAVA, iOS, python, ruby có thể tiêu thụ api của bạn. Trong các trình bao bọc này, bạn có thể bao gồm enum, sử dụng int in json và sau đó chỉ cần phân tích json của bạn thành một đối tượng với enum đã được đặt và trả lại đối tượng này cho mã người dùng.

Một điều bạn có thể làm là cung cấp cả hai. ví dụ:

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

Hoặc bạn có thể sử dụng loại và loạiStr tùy thuộc vào loại nào phù hợp nhất với api của bạn.

Và sau đó nêu rõ trong tài liệu của bạn rằng những thứ này là dư thừa và tùy thuộc vào nhà phát triển để chọn cái nào là tốt nhất cho ứng dụng của họ.

Hãy xem json tại đây: https://dev.twitter.com/docs/api/1/get/search Twitter có một ví dụ về việc cung cấp dữ liệu dư thừa (id và id_str), nhưng điều này bởi vì một số khách hàng json không thể phân tích được ints dài một "số" trong json và yêu cầu một chuỗi để tránh mất chữ số

— portforwardpodcast
nguồn