restful api规范

一、什么是restful

　　REST：（Representational State Transfer）中文：“表现层状态转移”，它是一种软件的架构风格、设计风格，提供了一组设计原则和约束条件，可以简单的理解成为一种规范。

　　RESTful：满足REST架构约束条件和原则的应用程序或设计就是 RESTful。

二、RESTful API接口规范

　　1、API（接口）与用户的通信协议，总是使用HTTPs（比HTTP更加安全）协议。

　　2、域名（根入口点）应尽可能的保持足够简单

https://api.example.com ：尽量将API部署在专用域名（会存在跨域问题）
https://example.org/api/：API很简单(推荐使用)

 　　3、版本号，为了保证所有的API向下兼容，在引入新版本API的同时确保旧的API版本可用，所以应提供版本支持。

目前比较常见的两种版本号形式：

1》、在 URL 中嵌入版本编号

    https://api.example.com/v1/

这种做法是版本号直观、易于调试

2》、通过媒体类型来指定版本信息（将版本号放入到请求头中）

    Accept: application/vnd.example.com.v1+json

其中 vnd表示 StandardsTree标准树类型，有三个不同的树： x， prs和 vnd。你使用的标准树需要取决于你开发的项目。

    未注册的树（ x）主要表示本地和私有环境
    私有树（ prs）主要表示没有商业发布的项目
    供应商树（ vnd）主要表示公开发布的项目

    后面几个参数依次为应用名称（一般为应用域名）、版本号、期望的返回格式。

至于具体把版本号放在什么地方，这个问题一直存在很大的争议，但由于我们大多数时间都在使用 Laravel开发， 应该使用 dingo/api 来快速构建应用，它采用第二种方式来管理 API版本，并且已集成了标准的 HTTPResponse。

　　4、路径（endpoint）：他是特定资源或资源集合的url，

设计是需要准寻的约定：
    1、URL 的命名 必须 全部小写；
    2、URL 中资源（ resource）的命名必须是名词，并且必须是复数形式
    必须 优先使用 Restful 类型的 URL；
    3、URL 中不能出现 -， 必须 用下划线 _ 代替；
    4、URL 必须 是易读的；
    5、URL 一定不可 暴露服务器架构。
示例：

    https://api.example.com/books
    https://api.example.com/animals
    https://api.example.com/zoos/{zoo}/animals
    https://api.example.com/animal_types
    https://api.example.com/employees

 　　5、method，对资源的具体操作类型，常用的有5个。

常用的5个HTTP动词：
    GET（SELECT）：从服务器取出资源（一项或多项）。
    POST（CREATE）：在服务器新建一个资源。
    PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
    PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
    DELETE（DELETE）：从服务器删除资源。

注意：
    删除资源 必须 用 DELETE 方法。
    创建新的资源 必须 使用 POST 方法。
    更新资源 应该 使用 PUT 方法。
    获取资源信息 必须 使用 GET 方法。

 　　6、过滤，如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数（通过在url上传参的形式传递搜索条件），过滤返回结果。

?limit=10：指定返回记录的数量。
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animaltypeid=1：指定筛选条件。

# 注：所有 URL参数 必须是全小写， 必须使用下划线类型的参数形式。

　　7、状态码，所有的 API响应， 必须遵守 HTTP设计规范， 必须选择合适的 HTTP状态码。

1xx     代表请求已被接受，需要继续处理
2xx     请求已成功，请求所希望的响应头或数据体将随此响应返回
3xx     重定向
4xx     客户端原因引起的错误
5xx     服务端原因引起的错误

　　8、错误处理，目前常见的返回错误信息的两种方式：

　　　　1、将错误详细放入HTTP响应首部；

　　　　2、直接放入响应实体中（更易读、易写，推荐使用，将error当作key）

{"error": "Invalid API key"}

　　9、返回结果，针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

　　10、返回结果中提供链接，Hypermedia API，RESTful API最好做到Hypermedia，连向其他API方法，使得用户不查文档，也知道下一步应该做什么

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

三、API

　　API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。   本质就是用于访问的接口。