接口设计规范

2016-04-12

概述

接口形式主要为 RESTful，但又不拘泥于 RESTful。

一个完整的 API 请求过程包括：

HTTP请求方式
URL Endpoint
请求数据
响应结果

下面分述之。

HTTP请求方式

HTTP Operation	Similar to SQL Stmt	Description
GET	SELECT	获取，查找
POST	CREATE	新增创建
PUT	UPDATE	在服务器更新资源（客户端提供改变后的完整资源）
PATCH	UPDATE	在服务器部分更新资源（客户端提供改变的属性）
DELETE	UPDATE	删除

URL Endpoint

URI指向的是唯一的资源对象/资源集合列表。
统一所有的 endpoint 使用复数使得 URL 更加规整，让API使用者更加容易理解，对开发者来说也更容易实现。

URL Endpoint 组成

一个完整的 URL Endpoint 依次是：

网络协议(HTTP, HTTPS)
服务器地址
版本
接口名称
参数（可选）
- GET 参数使用Query String 格式：如：查询时，过滤条件使用 Query String，如 ?offset=0&limit=10&sort=_created_at；参数列表应该被 encode 过
- 用来描述数据或者请求的元数据放Header中，例如 X-Result-Fields

示例：

GET https://api.example.com/v1/users/123456/profiles

说明：

API 与用户的通信协议，总是使用 HTTPS 协议。
尽量将API部署在专用域名之下：api.example.com
不使用大写字母；使用中线 - 代替下划线 _
版本控制的另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观
一些常见的参数。
- ?limit=10：指定返回记录的数量
- ?offset=10：指定返回记录的开始位置。
- ?page=2&per_page=100：指定第几页，以及每页的记录数。
- ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
- ?user_type_id=1：指定筛选条件

接口分类

分为对资源对象的CURD操作，服务型接口和系统设置三种。

资源对象的CURD操作

GET https://~/$version/trades            获取trades列表  
GET https://~/$version/trades/:id        根据id获取单个trade  
POST https://~/$version/trades           创建trade  
PUT https://~/$version/trades/:id        根据id更新trade  
PATCH https://~/$version/trades/:id      根据id部分更新trade  
DELETE https://~/$version/trades/:id     根据id删除trade

服务型接口

使用 services 标识：

https://~/services/$version/server-name

示例：

GET https://~/services/$version/search?q=filter?category=file  搜索
PUT https://~/services/$version/queued/jobs                    往任务队列里面添加一个新的任务  
DELETE https://~/services/$version/queued/jobs/:id             根据id删除任务

系统设置

使用 settings 标识：

https://~/settings/$version/server-name

如：更改界面语言环境

PUT https://~/settings/$version/gui/lang  
{  
    "lang": "zh-CN"  
}

more >>

查看全文 >>