restful规范

restful接口规范
HTTP API 接口规范

简介

本文档约束思维API开发流程，同时提供 API 设计风格建议。

本文档中使用的要求级别关键字（“必须”、“不得”、“必需”，“应”、“不应”、“应该”、“不应该”、“建议”、“可以”和“可选”）将按 RFC 2119 中的描述进行解释。

在本文档中，这些关键字使用粗体突出显示。

本文档参考Google Cloud API 设计指南

接口开发流程

1, 前端研发同学根据需求梳理成接口需求，输出YAPI定义（ 建议 同时提供基于TypeScript的*.d.ts定义)。2, 前端同学发起接口评审会议，与后端同学确定接口方案，并修订YAPI定义。3, 前后端同学同时基于约定的YAPI定义开始开发。4, 集成联调。5, 提交测试。

接口设计规范

1, 所有请求方法 必须 被映射到5个标准方法。

2, 所有接口的请求参数 必须 被严格定义。

3, 所有接口的返回结构 必须 被严格定义（不允许 出现字段名为xxxDTO或者数据类型为JSON字符串的情况）。

4, 两种风格的接口都是受到支持的：

符合RESTful 规范的 面向资源的 基础接口。

符合请求性能需求的面向页面的业务聚合型接口。

标准方法

HTTP 接口的“标准方法”包括：List、Get、Create、Update和Delete方法。

强制要求:

所有的接口行为必须 被合理、准确、无歧义地映射到这五个方法中的一种。

POST, PUT 方法的参数 必须 位于请求正文内（HTTP Request Body）. 数据格式（Content-Type)为application/json;

标准方法HTTP映射HTTP请求正文HTTP响应正文

ListGET 无资源列表

GetGET 无资源

CreatePOST 资源资源

UpdatePUT 资源资源

DeleteDELETE 无无

List 方法

List 方法用于提供某类资源的列表，例如：课堂列表，测评题试卷列表，任务列表 等。

强制行为:

必须使用 HTTPGET 动词

返回的资源列表元素必须 属于 “同一类型”,

建议行为:

建议支持常见的行为参数，例如：分页(page&pageSize) 、排序(sort) 、过滤 、字段筛选 。

元素字段建议 经过剪裁，必要时 建议 提供结果字段筛选功能。

示例

<== GET /classroom/

    ?teacherId=123

    &page=1

    &pageSize=20

    &date.gte=123123123

    &sort=date.desc

==> {

    data: [

        { code: 'CRxxxxx', teacherId: 123, ....}

        { ... }

        { ... }

    ]

}

Get 方法

Get 方法常用于请求某一特定的资源，通常是通过资源的ID或者资源的名称进行检索，例如：

GET /user 获取当前用户信息

GET /classroom/${code} 获取某个课堂信息

GET /post/$pos{t}_{i}d/comment/${comment_index} 获取某个帖子的某个评论

强制行为:

必须使用 HTTPGET 动词。

建议行为:

数据字段建议 经过剪裁，必要时 建议 提供结果字段筛选功能。

Create 方法

Create 方法常用于创建资源，例如：生成课堂, 生成订单, 生成考试报告 等。

强制行为:

必须使用 HTTPPOST 动词。

创建成功必须 返回HTTP 201 状态码

建议行为:

[if !supportLists]1. [endif]创建成功后建议 返回创建的实体，数据格式 建议 和对应的 Get 方法一致。

<== POST /classroom/

{

    courseware: 'math-l1-c1',

    lessonCode: 123123,

    ...

}

==> {

    code: 'MK1231231',

    courseware: 'math-l1-c1',

    lessonCode: 123123,

    ...

}

Update 方法

Update 方法常用于更新指定资源的相关信息，例如：更新手机号，更新预约时间，更新收货地址等。

强制行为:

必须使用HTTP PUT 动词

由于目前微信小程序的部分版本不支持客户端使用HTTP PATCH 动词，本规范约定 不允许 使用 HTTP PATCH 动词。

建议行为:

更新完成后建议 返回更新后的资源数据，格式 应该 与对应的Get方法一致。

示例

<== PUT /user

{

    username: 'jack',

}

==>

{

    userId: 12313,

    username: 'jack'

    birthday: '2018-11-11',

    ...

}

Delete方法

Delete 方法常用于删除某个资源, 或者标记某个资源处于失效状态，例如: 退出登陆（删除Session), 删除地址 等。

强制行为:1, 必须 使用 HTTP DELETE 动词。

<== DELETE /session

==> (空)

URL规范

为了让API 更易于被发现与理解，URL应该具有以下特点：

简单: 使用简单易懂的单词，避免冗余的描述, 例如:/evaluate/classes_list 应当改为 /evaluate/class/。

一致: 使用与大家达成一致的名词, 并保证在系统内名词解释是一致的, 例如:class, classroom, course, lesson等。

此外URL需遵守以下规范:

1, 由于URL对大小写不敏感，因此URL 必须 是小写的，并且用 _ 分割。2, List方法和Create方法对应的URL称为 Collection URL, 建议 以 /结尾。3, Get, Update, Delete 方法对应的URL称为 Resource URL, 不允许 以 /结尾。4, URL内单词的词性 应该 是 名词, 并且使用 单数形态。5, 用于获取指定ID的资源的URL，应该 将ID置于path内, 而 不应该 置于query内。6, URL内 应该 包含API版本, 例如: https://api.huohua.cn/v1/classroom。

示例:

GET /classroom/ 获取班级列表

GET /classroom/${code} 获取指定的班级详情

DELETE /session 退出登陆

POST /address/ 创建地址

GET /classroom/${code}/lesson 获取某班级的课次信息

GET /classroom/${code}/student/ 获取班级内学生列表

GET /classroom/$code/student/${student_id} 获取某班级内某学生信息

Bad Case:

POST /classroom/create 应该改成 POST /classroom/

GET /classroom/mk_list_by_user 应该改成 GET /classroom/?code_prefix=mk，by_user的行为应该由session 决定。

GET /classroomTeacher 应该改成 GET /classroom/${code}/teacher

GET /lesson/lesson_list 应该改成 GET /lesson/

接口输出

标准格式

API 返回应遵循以下格式。

名称类型说明

success　boolean用于表明本次请求成功与否

message　string用于输出本次接口结果消息，常用于表达错误消息。

code　number用于输出本次请求的状态码，常用于表达错误状态码。

data　any用于承载本次请求主要数据实体内容

API 返回中的 data 字段内包含本次接口返回的主要数据，数据字段应当遵守以下规则:

1, 数据结构嵌套 不应该 超过3层。2, 字段名 应该 遵循 小写 + _ 风格。3, 字段值 不应该 出现 JSON字符串 的形式。

异常输出

API 异常大致分为两类:

客户端异常: 客户端发起了不被允许的请求，例如登录凭证失效后访问/user接口等。这种情况下接口应该返回4xx 的HTTP状态码。

服务端异常: 由于服务器行为导致的异常应该返回5xx 的HTTP状态码。

两种异常在情况允许的情况下仍然应该按照标准格式 输出结果。