直白介绍 restfulAPI 以及如何 设计标准的 restfulAPI

• 英文翻译

Representational State Transfer 英文解释：表述（通常译为表征）性状态转移。

URI的设计应该遵循可寻址性原则，具有自描述性，需要在形式上给人以直觉上的关联

特点

1：REST强调资源，RPC强调动作，所以REST的Uri组成为名词，RPC多为动词短语。

2：更清晰API设计的可能会使用GET POST PUT DELETE四种方法分别代表“查询、添加、更新、删除”等四个动作，这在概念上是符合HTTP规范的

3：所有API的URI为基于HTTP的名词性短语，用来代表一种资源。

---

4：服务端接收到客户端的请求之后，统一返回200，如果客户端获取到的返回码不是200，代表链路上某一个环节出了问题。服务端所有的响应格式为:

 {    
     “code”: -32600, 
     “message”: “Invalid Request”, 
     “data”:{ }
 }

• code为0代表调用成功，其他会自定义的错误码
• message表示在API调用失败的情况下详细的错误信息，这个信息可以由客户端直接呈现给用户，否则为空
• data表示服务端返回的数据，具体格式由服务端自定义，API调用错误为空

---

• RESTful只要维护资源的状态，而不需要维护客户端的状态。
• 对它来说，每次请求都是全新的，它只需要针对本次请求作相应的操作，不需要将本次请求的相关信息记录下来以便用于后续来自相同客户端请求的处理。

设计原则

• 第一步：把所有起作用的数据都列出来。
• 第二步；将所有的数据用一种层级关系表示出来。
• 第三步：画出状态图。

tips:

对于API版本控制，一般最好的方法就是在URL前面加一个版本tag号，比如/v1/或者/v2/

比如一个超媒体控件就是一个状态转换。

---

任何安全状态转化都是幂等的，幂等是指不管触发一次还是多次，效果都是一样的。