HTTPTools

HTTP 201 Created

创建操作的成功响应:新资源现已存在,Location 说明其位置。

HTTP 201 是什么意思

当请求——几乎总是 POST 或 PUT——成功在服务器上创建了新资源时,会返回 HTTP 201 Created。REST API 用它来区分“现在有了新东西”与泛泛的 200 成功。

一个规范的 201 响应会包含指向新创建资源 URL 的 Location 头,并且通常会在响应体中回显所创建的对象,这样客户端就不需要再发一次 GET 请求。

201 响应的常见原因

  • POST 请求创建了一条记录、一个文件或一个账户。
  • PUT 请求在客户端提供的确切 URL 上创建了资源。
  • 一个批处理端点同步完成了一个主要资源的创建。

开发者的最佳实践

  • 将 Location 头设置为新资源的规范 URL。
  • 在响应体中返回已创建的表示(包含服务器分配的 id),以省去客户端的一次往返请求。
  • 如果创建过程是排队而非已完成,则应改为返回 202 Accepted。
  • 重复的相同 POST 导致重复创建?可以考虑使用幂等键,并对重放请求返回 200/409。

示例响应

HTTP/1.1 201 Created
Location: /api/users/1024
Content-Type: application/json

{"id":1024,"name":"New user"}

常见问题

200 和 201 有什么区别?

两者都表示成功,但 201 明确告诉客户端创建了新资源。200 只表示请求已被处理。

201 是否必须携带 Location 头?

强烈建议携带:它指向新创建资源的 URL,方便客户端获取或链接到该资源。

API 什么时候应返回 202 而不是 201?

当创建过程是异步进行时——202 表示请求已被接受,但资源尚不存在。