如何在公共API中表示（枚举）类型

我正在开发一个简单的API，我想将其用于自己的客户端，并在将来向公众开放。我有可以具有不同“类型”的“项目”对象。目前，该类型是C“ typedef枚举”：

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

（我将来可能会添加一些）

我想知道我是否应该将其转换为整数或定义的“字符串”。JSON为：

对于整数：

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

对于字符串：

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

我想知道是否有最佳实践。保留整数将稍微简化代码并减少带宽，但是字符串对于开发人员来说更容易记住。我记得我在一个项目上工作，我必须记住1 =图像，2 =音频，3 = html等。。。这没有任何实际意义。

所以我问你，如果你知道我应该考虑的其他方面。

提供字符串。数字是没有意义的。您没有在自己的代码中使用它们，对（您将枚举值包装在一起，基本上是字符串）-为什么要用这些数字来惩罚用户？

如果您确实公开了数字，那么这是唯一的专业人士-便于您解析这些数字。但是，嘿，谁在乎你。照顾好API客户端。

如果您提供字符串-对客户来说更容易；永远不必说“ 4已弃用17，而不再赞成”之类的话；代表您进行解析时稍微困难一点，但这很好。

不要同时提供：作为用户，我想知道

• 我要使用哪一个？都？[关于阅读文档]
• 为什么有两种方式说同一件事？它们有细微的不同吗？[关于阅读文档]
• 如果我同时指定两者并且不匹配怎么办？会抱怨吗？一个会优先吗？哪一个？[关于阅读文档]

如您所见，您让我无缘无故地阅读了许多文档。

字符串。

Json的强项之一是其可读性。从现在开始半年调试输出时，“ 0”不会告诉您任何信息。

某些框架也会进行自动转换。如果您不使用它-您可以自己创建一个转换器以保持代码干燥。

不过，这将进行投票。

最佳做法取决于谁在使用您的API。如果您想让消费者过上轻松的生活，则应使用C，JAVA，iOS，python，ruby提供可以消耗您的api的示例代码。在这些包装器中，您可以包括枚举，在json中使用int，然后将json解析为已设置枚举的对象，然后将该对象返回给用户代码。

您可以做的另一件事是同时提供两者。例如：

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

或者，您可以使用type和typeStr，具体取决于哪种API最适合您。

然后在您的文档中明确指出它们是多余的，并且由开发人员选择最适合其应用程序的。

在这里查看json：https : //dev.twitter.com/docs/api/1/get/search Twitter有提供冗余数据（id和id_str）的示例，但这是因为某些json客户端无法从中解析长整数。 json中的“数字”，需要一个字符串以避免丢失数字