RESTAPI：当资源存在但已过期时，正确的响应格式和状态代码是什么？

Question

假设我们有资源Employee 。 Employee 看起来像这样（从实体和数据库的角度来看）：

{
    id: 123,
    name: "John Doe",
    // more props here
    workPermitExpireDateUTC: "1999-06-30 00:00:00"
}

当我们查询所有员工时，我们要显示附加标志isExpired计算：

GET: /api/employees ：

// HttpStatuCode: 200
[
    {
        id: 123,
        name: "John Doe",
        // more props here
        workPermitExpireDateUTC: "1999-06-30 00:00:00",
        workPermitExpired: true // calculated on a fly, based on system clock
    },
    {
        id: 456,
        name: "George Smith",
        // more props here
        workPermitExpireDateUTC: "2025-06-30 00:00:00",
        workPermitExpired: false // calculated on a fly, based on system clock
    }
]

当我查询单个未过期员工时

GET /api/employess/456我希望得到200 Response ——这很明显。

但是，如果我们考虑过期的员工，我不想发送所有数据，因为客户不需要知道它。 所以我的想法是这样返回：

GET: /api/employees/123 ：

// HttpStatuCode: 200
{
    id: 123,
    workPermitExpired: true,
    errorMessage: "Employee work permit expired"
}

但感觉不对，因为200响应不应该有不同的结构，具体取决于资源 ID。

这样的 url GET: /api/employees/123/non-expired并在未过期的情况下返回200 ，在过期的情况下返回410 ？

Answer 1

当资源存在但已过期时，正确的响应格式和状态代码是什么？

An important thing to understand in REST, is that our API is a facade , deliberately designed to make our domain look like every other dumb document store on the web, so that all of the general purpose web tools "just work".

另一种说法是：HTTP 是通过网络传输文档领域的应用程序。 当我们构建 REST API 时，我们正在做的是我们正在调整我们的域协议以适应与客户端交换文档的语言。

状态代码和标题属于网络传输文档域。

GET: /api/employees/123

对此的正确响应很大程度上取决于我们是否拥有该资源的当前表示（这是传输文档域的关注点）。 我们领域中该表示的语义实际上并没有涉及到它。

如果我们有资源的当前表示，那么这很好

200 OK
Content-Type: application/json

{
    "id": 123,
    "workPermitExpired": true,
    "errorMessage": "Employee work permit expired"
}

当我们无法满足提供当前资源的请求时，我们通常会使用状态码向通用组件指示响应正文描述了错误条件，而不是资源的表示。

404 Not Found
Content-Type: application/json

{ "error": "Who is 123?" }

感觉不对，因为 200 响应不应该有不同的结构，具体取决于资源 ID。

正确的。 这通常翻译的方式是更仔细地定义您的架构。 如果您希望在表示中打开和关闭某些字段，那么您的架构定义需要将这些字段描述为可选的。 例如，我们可能会描述一个“活动许可”模式和一个“过期许可”模式（在不同的键下），其约束条件是客户端应该期望一个或另一个，但不能两者兼而有之。

另一种可能性是对不同的表示使用不同的内容类型。 RFC 6838是您查找详细信息的地方，但粗略的大纲是我们将定义两个不同的模式，然后为每个模式分配不同的内容类型

• 应用程序/prs.maciej-active-permit+json
• 应用程序/prs.maciej-过期许可+json

application/+json告诉通用消费者这些表示“只是” json 文档，但熟悉您的特定媒体类型的消费者将有更具体的理解来使用。

RFC 7807是这种方法的标准化演示，其中字段名称的特定语义被编码到 json 文档中，媒体类型application/problem+json告诉通用组件真正发生了什么。

您在application/merge-patch+json和application/json-patch+json中看到了类似的想法。

Answer 2

从技术上讲，过期员工与员工的资源类型不同，例如

class ExpiredEmployee extends Employee

所以200是合适的，因为你没有返回Employee 。 您正在返回一个ExpiredEmployee 。

如果客户正在寻找员工，他们大概不关心过期的员工，因为他们在技术上不是员工？ 所以主要的 url 将是：

GET /api/employess/456用于未过期的员工

您可以按照业务线来设计 URL。 为什么会有人想要找到过期的员工？ 他们需要未过期吗？ 如果他们过期了，为什么他们仍然被视为员工？ 如果客户的主要业务线是与员工合作，那么为过期员工设置一个单独的资源端点似乎是合适的，因为一个单独的业务流程可能会为他们工作。

如果客户不希望员工过期，则返回的 object 可能会使他们感到困惑。 也许一个单独的业务线端点适合过期员工：

GET /api/employess/expired/456用于过期员工

因为大概任何正在寻找456的人已经知道他们已经过期并且想要改变他们的状态？