Cómo representar tipos (enum) en una API pública

32

Estoy trabajando en una API simple que quiero usar para mi propio cliente y abrirla al público en el futuro. Tengo objetos "Item" que pueden tener diferentes "tipos". El tipo es un C "typedef enum", por el momento tengo:

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

(Puedo agregar algunos en el futuro)

Me pregunto si prefiero transferirlo como enteros o como "cadenas" definidas. El JSON sería:

Para enteros:

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

Para cuerdas:

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

Me pregunto si hay una mejor práctica para esto. Mantener el número entero simplificaría un poco el código y reduciría el ancho de banda, pero las cadenas serían más fáciles de recordar para los desarrolladores. Recuerdo que trabajé en un proyecto, y tuve que recordar 1 = imagen, 2 = audio, 3 = html, ... lo cual no tiene ningún sentido real.

Entonces le pregunto, si conoce algún otro aspecto que debería considerar.

api patterns-and-practices enum Julien
fuente
¿Espera que sus usuarios editen el JSON manualmente a menudo?
James

Respuestas:

39

Proporcionar las cuerdas. Los números no tienen sentido. No los usa en su propio código, correcto (está envolviendo valores de enumeración, que son básicamente cadenas): ¿por qué castigar al usuario por tener que usar estos números?

El único profesional si expone los números, es más fácil analizarlos. Pero bueno, a quién le importas. Cuida a los clientes API.

Si proporciona las cadenas, más fácil para los clientes; nunca tendrá que decir cosas como "4 habían quedado en desuso a favor de 17"; análisis un poco más difícil en su nombre, pero está bien.

No proporcione ambos: como usuario, me pregunto

  • cual uso ¿Ambos? [a leer documentos]
  • ¿Por qué hay dos maneras de decir lo mismo? son sutilmente diferentes? [a leer documentos]
  • ¿Qué pasa si especifico ambos y hay una falta de coincidencia? ¿se quejará? ¿tendrá prioridad? ¿cúal? [a leer documentos]

Como puede ver, me está haciendo leer muchos documentos sin ninguna razón.

iluxa
fuente
Estoy de acuerdo con @iluxa
portforwardpodcast
1
¿Qué pasa si enum es miembro de la clase (objeto) esperado como entrada en la llamada de descanso?
semental
2

Instrumentos de cuerda.

Una de las fortalezas de Json es que es legible para los humanos. Al depurar la salida dentro de medio año a partir de ahora "0" no le dirá nada.

Algunos marcos también harán la conversión automática. Si no está usando uno, puede crear un convertidor usted mismo para mantener su código seco.

Sin embargo, esto se traduce en una votación.

Evgeni
fuente
1

Las mejores prácticas dependen de quién consume su API. Si está tratando de facilitarle la vida al consumidor, debe proporcionar un código de muestra en C, JAVA, iOS, python, ruby ​​que pueda consumir su API. En estos contenedores puede incluir la enumeración, usar un int en json, y luego simplemente analizar su json en un objeto con la enumeración ya establecida, y devolver este objeto al código de los usuarios.

Otra cosa que podría hacer es proporcionar ambos. por ejemplo:

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

O puede usar type y typeStr según lo que se vea mejor para su api.

Y luego indique claramente en su documentación que estos son redundantes y depende del desarrollador elegir cuál es el mejor para su aplicación.

Mire el json aquí: https://dev.twitter.com/docs/api/1/get/search Twitter tiene un ejemplo de proporcionar datos redundantes (id e id_str), pero esto porque algunos clientes json no pueden analizar largas entradas desde un "número" en json y requiere una cadena para evitar perder dígitos

portforwardpodcast
fuente