Restful 接口设计规范 VS SOAP

Restful 接口规范

对于资源的具体操作类型，由HTTP动词表示。

• 常用的HTTP动词有下面五个（括号里是对应的SQL命令）。
  GET（SELECT）：从服务器取出资源（一项或多项）。
  POST（CREATE）：在服务器新建一个资源。
  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  DELETE（DELETE）：从服务器删除资源。

• 还有两个不常用的HTTP动词。
  HEAD：获取资源的元数据。
  OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

• 举例接口规范 GET /employees 列出所有员工 POST /employees 新建一个员工
  GET /employees/:id 获取指定员工信息 DELETE /employees/:id 删除指定员工信息

• HTTP 动词

1. GET 从服务器取出一项或者多项资源
2. POST 在服务器新建一个资源
3. PUT 在服务器更新资源 (客户端提供改变后的完整资源?)
4. PATCH 在服务器更新资源 (客户端提供改变的属性?)
5. DELETE 从服务器删除资源

• 过滤信息 使用url参数添加一些过滤信息

1. ?sortBy=name&order=asc 根据name来排序并且升序
2. ?limit=10 返回记录限制为10条 ....

• 常见的返回状态码

1. 200 OK [GET]
2. 201 CREATED [POST,PUT,PATCH] 用户新建或者修改数据成功
3. 400 INVALID REQUEST [POST,PUT,PATCH] 用户发出的请求有误(E.g.服务器必须的参数用户没有提供)
4. 401 Unauthorized 用户没有权限(令牌,用户名,密码错误)
5. 403 Forbidden 表示用户得到了授权, 但是访问是被禁止的(没有访问该资源的权限)
6. 404 NOT FOUND 用户发出的请求资源是不存在的
7. 500 服务器内部处理错误, 用户无法判断请求是否成功

• 其他

1. API身份验证应该使用OAuth 2.0框架
2. 服务器放回数据格式,应该尽量使用JSON,避免XML

SOAP

• SOAP 提供了自己的协议并专注于公开某些应用逻辑(不是数据)为服务。SOAP 公开的是操作。SOAP 专注于访问通过不同的接口实现了某些业务逻辑的命名操作。

转载并截取自RESTful API 设计指南 soap和rest的区别