.

状态码

https

Http状态码

返回结果的设计

状态码

标准示例

通用错误码

还是记录下相应的状态码

鉴权

restful接口规范

请求语言

接口规范

状态吗

HTTP状态码

REST API：

REST API 接口规范：

内容：

rest api 接口实例

rest api 接口实例

接口？接口测试？rest？SOAP协议？安全。接口规范？接口实例？

rest api 接口规范 状态码

REST API 接口规范3

REST API 接口规范2

REST API 接口规范

REST 补充概念

REST API 接口规范：返回结果 设计

返回结果 设计是检验产品是否具有良好用户体验的关键。

1. 通用错误码，具体产品由具体产品api文档给出。

{“msg":"uri_not_found", "code":1001, "request":"GET\/v2\/photo\/132"}

REST API 接口规范：

常见HTTP Status code 状态码：

200 OK 

201 created

202 accepted

301 moved permanently

303 see other 

400 bad request

404 not found

406 not acceptable

409 conflict

412 precondition failed

415 unsupported media type

500 internal server error

503 service unavailable, i.e 应用池过高、消息队列太多、当前服务器无法处理，等待30秒或10秒server自动恢复前报503；

REST API 接口规范

设计规范：

协议： 建议使用HTTPS协议，确保交互数据的传输安全

域名：应该尽量将API部署在专用域名之下。i.e https://api.example.com

版本控制：将版本号放在URL或Header中

路径：只能包含名词，不能包括动词

过滤信息： ？limit=10  ?offset=10  ?page=1  ?sortby=name 

Hypermedia API: 在返回结果中提供相关资源的链接，连向其他API方法

验证（Authentication）: 确定用户是其申明的身份，比如提供账户的密码。

授权（Authorization）: 保证用户有对请求资源特定操作的权限。比如 用户的私人信息只能自己访问，其他人无法看到；有些特殊的操作只能管理员可以操作，其他用户有只读的权限等。

幂等性(Idempotent): 是一个数学上的概念，在这里批表示发送一次和多次请求引起的边界效应是一致的，post方法是不幂等，get是幂等。

安全性：GET,HEAD 和 OPTIONS 均被认为是安全的方法，因为它们指在实现对数据的获取，并不具有'边界效应(side effect)'

常见HTTP状态码

200(ok) – 请求已成功，请求所希望的响应头或数据体将随此响应返回

201(created) – 请求已经被实现，而且有一个新的资源已经依据请求的需要而建立

202(accepted) – 已接收处理请求但尚未完成（异步处理）

301(moved permanently) – 资源的URI被更新

303(see other) – 其他（如负载均衡）

304(Not Modified) – 没有变化，客户端可以使用缓存数据

400(Bad Request) – 指代坏请求，确切的错误应该在error payload中描述，例如：“JSON 不合法 ”

401(Unauthorized) – 未认证，当前请求需要用户验证

403(Forbidden) – 服务器已经理解请求，但是拒绝执行

404(not found) – 资源不存在

406(not acceptable) – 请求的资源的内容特性无法满足请求头中的条件，因而无法生成响应实体

412(precondition failed) – 服务器在验证请求头中给出先决条件时，没能满足其中的一个或多个

415(unsupported media type) - 请求中提交的实体并不是服务器中所支持的格式(请求中的内容类型是错误的)

500(Internal Server Error) – 标准服务端错误，API开发人员应该尽量避开这种错误

503(service unavailable) - 服务当前无法处理请求（临时的服务器维护或者过载）

REST API 接口实例

• GET /product：列出所有商品

• POST /product：新建一个商品

• GET /product/ID：获取某个指定商品的信息

• PUT /product/ID：更新某个指定商品的信息

• DELETE /product/ID：删除某个商品

• GET /product/ID/purchase：列出某个指定商品的所有投资者

• GET /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

返回结果设计

通用错误码，具体产品由具体产品 api 文档给出。

{
    "msg":"uri_not_found",
    "code":1001,
    "request": "GET \/v2\/photo\/132"
 }