整体规范建议采用Restful方式来实施。
协议:API与用户的通信协议,应该使用https协议,确保交互数据的安全传输。
域名:应该尽量将API部署在专用域名下。如:https://api.example.com。
api版本控制:
方法一:将API的版本号放入URI,如:https://api.example.com/v1。
方法二:将版本号放在http头信息中。这种方法不如放入url中方便和直观。
采用多版本并存,增量发布的方式,v{n}n代表版本号,分为整形和浮点型。
整形的版本号:大功能发布的版本,改动比较多。
浮点型:小版本号,只增加或修改了很小一部分东西。
api路径规则:
路径又称"终点"(endpoint),表示API的具体网址。在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词。
HTTP请求方式:
对于资源的具体操作类型,由http的动词表示。
常用的HTTP动词有下面四个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PU