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。
等等.........