RESTful API

API

API 是应用程序接口,是一段充当两个异构软件间的过渡代码。API 作为双方的中介或翻译，来回传递request和response，同时仅公开完成数据处理所需的代码。

eg：当软件实施了社交登录后，用户只需单击一下按钮即可通过身份提供商进行身份验证，例如「使用微信登录」。是腾讯向开发者提供了 API 以帮助用户使用微信身份登录到开发者的应用。

API-first

本质上，API-first 体系架构是一种软件设计的方法，它以 API 为中心，创建可以轻松互连的应用程序。API-first 开发出来的应用程序生态像乐高积木一样模块化、可重用、可扩展。如果你不是开发者的话并不需要掌握太多技术要点，但你一定需要了解 API-first 对你的业务带来的影响。

API 是模块化的且可复用的，因此 API-first 的体系结构可加快开发过程。API 帮助促进微服务的使用，微服务是可以插入任何应用程序的独立功能。API-first 的体系结构使开发人员可以更高效地上线新功能，而且可以让外部应用程序更容易的嵌入进来。

RESTful API

RESTful API：REST风格的API，典型的基于HTTP的协议，是目前比较成熟的一套互联网应用程序的API设计理论。现在终端平台多样，移动、平板、PC等许多媒介向服务端发送请求后，如果不适用RESTful API，需要为每个平台的数据请求定义相应的返回格式，以适应前端显示。但是RESTful API 要求前端以一种预定义的语法格式发送请求，那么服务端就只需要定义一个统一的响应接口，不必像之前那样解析各色各式的请求。

1、API与用户的通信协议，总是使用https协议。应该尽量将API部署在专用域名之下。如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

 eg：以微博为例，

（1）新浪微博开放平台-首页https://open.weibo.com/这个是微博的一个开放接口。像open、api，都是一个单独的后端域名。

如果你自己想写一个微博，那么微博的数据就可以借用新浪微博提供给你的接口，数据库用的官方公开的数据库。

​

（2）Sina Visitor Systemhttps://weibo.com/

这个是微博的一个前端域名。

​

2、应该将API的版本号放入URL。

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo

3、路径

• 在RESTful架构中，每个网址代表一种资源resource，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。

错误例子：

/getProducts

/listOrders

/retreiveClientByOrder?orderId=1

• 一般来说，数据库中的表都是同种记录的"集合"，所以API中的名词也应该使用复数，无论子资源或者所有资源。

获取所有商品
http://127.0.0.1:8000/Appname/rest/products

获取单个商品
http://127.0.0.1:8000/Appname/rest/products/1

4、HTTP动词

请求方法	请求地址	后端操作
GET	/goods	获取所有商品信息
POST	/goods	增加商品
GET	/goods/1	获取编号为1的商品
PUT	/goods/1	修改编号为1的商品
DELETE	/goods/1	删除编号为1的商品

5、如果记录数量很多，API应该提供参数，过滤返回结果。

?limit=10    指定返回记录的数据

?offeset=10    指定返回记录的开始位置

?page=4&per_page=100    指定第几页，每页有多少记录

?sortby=name&order=asc    指定返回结果按照什么排序，以及排序顺序

?animal_type_id=1    指定筛选条件

6、错误处理

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

7、超媒体

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

8、其他

服务器返回的数据格式，应该尽量使用JSON，避免使用XML。

等等.........