Como representar tipos (enum) em uma API pública

32

Estou trabalhando em uma API simples que quero usar para meu próprio cliente e para abrir ao público no futuro. Eu tenho objetos "Item" que podem ter "tipos" diferentes. O tipo é um "typedef enum" C, por enquanto tenho:

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

(Eu posso adicionar alguns no futuro)

Gostaria de saber se devo transferi-lo como números inteiros ou como "strings" definidas. O JSON seria:

Para números inteiros:

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

Para strings:

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

Gostaria de saber se existe uma prática recomendada para isso. Manter o número inteiro simplificaria um pouco o código e reduziria a largura de banda, mas as strings seriam mais fáceis de serem lembradas pelos desenvolvedores. Lembro que trabalhei em um projeto e tive que lembrar 1 = imagem, 2 = áudio, 3 = html, ... o que não faz nenhum sentido.

Então, eu estou lhe perguntando, se você conhece algum outro aspecto que eu deva considerar.

api patterns-and-practices enum Julien
fonte
Você espera que seus usuários editem o JSON manualmente com frequência?
James

Respostas:

39

Forneça as cordas. Os números não têm sentido. Você não os usa no seu próprio código, certo (você está agrupando valores de enumeração, que são basicamente strings) - por que punir o usuário por ter que usar esses números?

O único profissional se você expuser os números - é mais fácil analisá-los. Mas ei, quem se importa com você. Cuide dos clientes da API.

Se você fornecer as strings - mais fácil para os clientes; nunca precisará dizer coisas como "4 foram preteridas em favor de 17"; análise um pouco mais difícil em seu nome, mas tudo bem.

Não forneça os dois: como usuário, fico me perguntando

  • qual eu uso? Ambos? [para ler documentos]
  • por que existem duas maneiras de dizer a mesma coisa? eles são sutilmente diferentes? [para ler documentos]
  • e se eu especificar os dois e houver uma incompatibilidade? vai reclamar? alguém terá precedência? qual? [para ler documentos]

Como você pode ver, você está me fazendo ler muitos documentos sem motivo.

iluxa
fonte
Eu concordo com @iluxa
portforwardpodcast
1
E se o enum for membro da classe (objeto) esperado como entrada na chamada de descanso?
garanhão
2

Cordas.

Um dos pontos fortes de Json é que é legível por humanos. Ao depurar a saída daqui a meio ano, "0" não informa nada.

Algumas estruturas também farão a conversão automática. Se você não estiver usando um - você mesmo pode criar um conversor para manter seu código seco.

No entanto, isso resulta em uma votação.

Evgeni
fonte
1

A melhor prática depende de quem está consumindo sua API. Se você estiver tentando facilitar a vida do consumidor, forneça um código de exemplo em C, JAVA, iOS, python, ruby ​​que possa consumir sua API. Nesses wrappers, você pode incluir o enum, usar um int em json e, em seguida, apenas analisar seu json em um objeto com o enum já definido e retornar esse objeto ao código do usuário.

Outra coisa que você pode fazer é fornecer os dois. por exemplo:

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

Ou você pode usar type e typeStr, dependendo da aparência da sua API.

E então declare claramente em sua documentação que são redundantes e cabe ao desenvolvedor escolher qual é o melhor para sua aplicação.

Veja o json aqui: https://dev.twitter.com/docs/api/1/get/search O Twitter tem um exemplo de fornecimento de dados redundantes (id e id_str), mas isso porque alguns clientes json não conseguem analisar entradas longas de um "número" em json e requer uma string para evitar a perda de dígitos

portforwardpodcast
fonte