REST API 状态为整数还是字符串？

Question

我和我的同事正在研究 REST API。我们一直在争论资源/项目的状态应该是字符串还是整数——我们都需要读取、理解和修改该资源（使用单独的应用程序）。由于这是一个非常普遍的主题，谷歌没有帮助解决这个争论。我想知道您的经验是什么以及哪种方式更好。

例如，假设我们有Job资源，可以通过 URI http://example.com/api/jobs/someid访问该资源，并且它具有以下 JSON 表示形式，存储在 NoSQL DB 中：

JOB A:
{
   "id": "someid",
   "name": "somename",
   "status": "finished"  // or "created", "failed", "compile_error"
}

所以我的问题是 - 也许它应该更像是以下？

JOB B:
{
   "id": "someid",
   "name": "somename",
   "status": 0  // or 1, 2, 3, ...
}

在这两种情况下，我们每个人都必须创建一个地图，用它来理解应用程序逻辑中的状态。但我自己倾向于第一个，因为它更具可读性......您也可以轻松地混淆“0”（字符串）和0（数字）。

然而，由于 API 是被机器使用的，所以可读性并不那么重要。使用数字还有一些其他优点 - 在控制台中使用应用程序时它被广泛接受，并且当您想要包含任意新的失败状态时，它会很有用，例如：

• status == 50 - 表示您的网络组件 X 有问题，
• status > 100 - 表示一些多种特殊情况。

当您有数字时，您不需要为它们组成所有这些字符串名称。那么您认为哪种方式最好？也许我们需要多个字段（这可能会让事情变得有点混乱）：

JOB C:
{
   "id": "someid",
   "name": "somename",
   "status": 0, // or 1, 2, 3...
   "error_type": "compile_error",
   "error_message": "You coding skill has failed. Please go away"
}

Answer 1

就我个人而言，我会考虑结合您提到的两种方法来处理这种情况。我会将状态作为整数存储在数据库中，但会创建一个枚举或常量类，以将状态名称映射到数字状态值。

例如（在 C# 中）：

public enum StatusType
{
    Created = 0,
    Failed = 1,
    Compile_Error = 2,

    // Add any further statuses here.
}

然后，您可以将数据库中存储的数字状态转换为该枚举的实例，并在整个代码中使用它进行决策。

例如（在 C# 中）：

StatusType status = (StatusType) storedStatus;

if(status == StatusType.Created)
{
    // Status is created.
}
else
{
   // Handle any other statuses here.
}

如果您很迂腐，您也可以将这些映射存储在数据库中。

对于通过 API 进行访问，您可以根据您的要求选择任一方式。您甚至可以返回包含状态号和状态文本的结果：

object YourObject
{
    status_code = 0,
    status = "Failed"
}

您还可以创建一个 API 来从代码中检索状态名称。然而，从性能的角度来看，在 API 中返回状态代码和名称将是最好的。