REST命令即HTTP标准方法(如GET、POST、PUT、DELETE),用于对资源执行创建、读取、更新和删除操作,需严格遵循REST原则与安全规范。
核心REST命令列表及用途
HTTP方法 | 作用 | 幂等性 | 安全 | 典型应用场景 |
---|---|---|---|---|
GET |
获取资源 | 是 | 是 | 查询用户列表、读取商品详情 |
POST |
创建新资源 | 否 | 否 | 新增订单、提交表单数据 |
PUT |
更新/替换整个资源 | 是 | 否 | 修改用户全部信息 |
PATCH |
更新资源部分属性 | 否 | 否 | 修改用户邮箱或状态 |
DELETE |
删除资源 | 是 | 否 | 移除文章、注销账号 |
HEAD |
获取资源元数据 | 是 | 是 | 检查资源是否存在 |
OPTIONS |
查询服务器支持的HTTP方法 | 是 | 是 | 预检请求(CORS) |
详细命令用法与示例
GET – 安全读取数据
- URL设计:
/users
(获取所有用户)或/users/{id}
(获取单个用户) - 请求示例:
curl -X GET https://api.example.com/users/123
- 响应:返回状态码
200 OK
+ JSON数据(如用户信息)。
POST – 创建新资源
- URL设计:
/users
(指向资源集合) - 请求头:
Content-Type: application/json
- 请求体(JSON格式):
{ "name": "张三", "email": "zhangsan@example.com" }
- 请求示例:
curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -d '{"name":"张三","email":"zhangsan@example.com"}'
- 响应:状态码
201 Created
+Location: /users/456
(返回新资源路径)。
PUT – 全量更新资源
- URL设计:
/users/{id}
(指定具体资源) - 请求体:需包含资源全部属性(缺失字段会被置空):
{ "id": 123, "name": "张三", "email": "new_email@example.com" }
- 请求示例:
curl -X PUT https://api.example.com/users/123 \ -H "Content-Type: application/json" \ -d '{"id":123,"name":"张三","email":"new_email@example.com"}'
- 响应:
200 OK
(更新成功)或204 No Content
。
PATCH – 部分更新资源
- URL设计:
/users/{id}
- 请求体:仅传递需修改的字段:
{ "email": "updated@example.com" }
- 请求示例:
curl -X PATCH https://api.example.com/users/123 \ -H "Content-Type: application/json" \ -d '{"email":"updated@example.com"}'
- 响应:
200 OK
+ 更新后的完整资源。
DELETE – 删除资源
- URL设计:
/users/{id}
- 请求示例:
curl -X DELETE https://api.example.com/users/123
- 响应:
204 No Content
(删除成功)。
关键注意事项
-
幂等性:
GET
、PUT
、DELETE
、HEAD
、OPTIONS
可重复执行且结果不变。POST
和PATCH
非幂等(多次调用可能产生不同结果)。
-
安全性:
- 仅
GET
、HEAD
、OPTIONS
是安全的(不修改资源)。 - 敏感操作(如
DELETE
)需身份验证(如OAuth 2.0)。
- 仅
-
URL设计规范:
- 使用名词复数(如
/products
而非/getProducts
)。 - 层级关系:
/users/{userId}/orders
(用户的所有订单)。
- 使用名词复数(如
-
状态码使用:
200 OK
:成功请求400 Bad Request
:客户端错误401 Unauthorized
:未认证404 Not Found
:资源不存在500 Internal Server Error
:服务端错误
-
安全实践:
- 必须使用HTTPS加密传输。
- 对
POST
/PUT
/PATCH
请求做数据验证(防XSS/SQL注入)。 - 限流机制(防止DDoS攻击)。
常见问题解答
Q:PUT和PATCH有什么区别?
A:PUT
要求传递完整资源,未传字段会被清空;PATCH
仅更新指定字段,其他字段保持不变。
Q:如何选择POST还是PUT创建资源?
A:若客户端知道资源ID(如用户ID),用PUT /users/{id}
;若由服务器生成ID,用POST /users
。
Q:REST命令必须返回JSON吗?
A:不是,但JSON是主流格式,也可支持XML(需设置Accept: application/xml
)。
REST命令通过标准化HTTP方法操作资源,是构建API的通用范式,正确使用需遵循:
- 语义化URL(资源导向)
- 幂等性与安全性(保障系统可靠性)
- 状态码与错误处理(明确反馈结果)
- HTTPS+身份验证(基础安全要求)
掌握这些原则,可设计出易用、高效且安全的RESTful API。
引用说明参考自HTTP/1.1规范(RFC 7231)、Roy Fielding的REST架构论文,以及Google Cloud API设计指南,实践建议结合OWASP安全标准。
原创文章,发布者:酷番叔,转转请注明出处:https://cloud.kd.cn/ask/6213.html