前段时间面试,问到restful APi的相关知识点, 原来只是用过,没有系统的总结,现在坐下记录,供后续查询 

1 什么是RESTful API

REST(Representational State Transfer) 是一种架构风格,  倾向于用更加简单轻量的方法设计和实现。

值得注意的是REST并没有一个明确的标准，而更像是一种设计的风格

 如果你们使用的是REST接口,则你们的接口就是  RESTful的;

百度百科 的定义如下

一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

2 相关规范

2.1 协议

 API与用户的通信协议,应尽量使用https协议,确保数据传输的安全性

       2.2 域名

应尽量将API部署到专用域名之下,例如

https://www.baidu.com

 通用的URL语法 ( [ ] 为可选项)

protocol :// hostname[:port] / path / [;parameters][?query]#fragment

URL示例:  http://127.0.0.1:8089/myProject/login.jsp

其中:

• protocol :协议, 指定使用的传输协议,例如 http,https,ftp等
• hostname: 主机名,指的是存放资源的域名地址或IP地址
• port : 端口号, 整数，可选，省略时使用方案的默认端口，各种传输协议都有默认的端口号，如http的默认端口为80。如果输入时省略，则使用默认端口
• path: 路径, 由零或多个“/”符号隔开的字符串，一般用来表示主机上的一个目录或文件地址。
• paramters:参数, 这是用于指定特殊参数的可选项。
• query : 可选，用于给动态网页（如使用CGI、ISAPI、PHP/JSP/ASP/ASP。NET等技术制作的网页）传递参数，可有多个参数，用“&”符号隔开，每个参数的名和值用“=”符号隔开。
• fragment :信息片段, 字符串，用于指定网络资源中的片断。例如一个网页中有多个名词解释，可使用fragment直接定位到某一名词解释。

     2.3版本控制

应该将API的版本号放入到URL中

https://www.baidu.com/v{n}/

v{n} n代表版本号,分为整形和浮点型

整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2

浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

 2.3路径规则

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词,动词由HTTP的 get、post、put、delete 四种方法来表示，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

示例:

https://www.baidu.com/v1/users

https://www.baidu.com/v1/orgs

https://www.baidu.com/v1/students

2.4HTTP请求方式

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

常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。

POST（CREATE）：在服务器新建一个资源。

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

DELETE（DELETE）：从服务器删除资源。

示例:

GET /product：列出所有商品

POST /product：新建一个商品

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

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

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

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

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

2.5 过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

?pageNum=2&pageSize=100：指定第几页，以及每页的记录数。

2.7 返回结果

一般包括,状态码, 数据,提示信息

示例

标准HTTP状态码

• 200 OK 服务器返回用户请求的数据，该操作是幂等的
• 201 CREATED 新建或者修改数据成功
• 204 NOT CONTENT 删除数据成功
• 400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
• 401 Unauthoried 表示用户没有认证，无法进行操作
• 403 Forbidden 用户访问是被禁止的
• 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
• 500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
• 503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等

一条完整的API示例

1 功能: 上传一张图片

  请求地址:  http://你的地址/api/ file

请求方式:POST

请求参数说明

返回实例：

{

    "status": 0,

    "info": "没有上传的文件！",

    "data": ""

}