RESTful规范建议
RESTful概述
RESTful是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。
REST是Representational State Transfer的缩写,是Roy Thomas Fielding在他2000年的博士论文中提出的。其提出的设计概念和准则为:
1. 网络上的所有事物都可以抽象为资源
2. 每个资源都应该有唯一的标识(identifier),对资源的操作不会改变标识
3. 所有的操作都是无状态的
4. 使用标准方法(GET、POST、PUT、PATCH、DELETE)操作资源
RESTful使用
HTTP方法 | URI | 描述 | 幂等 | 安全 |
GET | /api/members | 获取成员列表 | 是 | 是 |
GET | /api/members/{id} | 获取指定成员 | 是 | 是 |
POST | /api/members | 创建一个成员 | 否 | 否 |
PUT | /api/members/{id} | 更新成员所有信息 | 是 | 否 |
PATCH | /api/members/{id} | 更新成员部分信息 | 是 | 否 |
DELETE | /api/members/{id} | 删除指定成员 | 是 | 否 |
HTTP方法 | URI | 描述 | 幂等 | 安全 |
GET | /api/groups | 获取群组列表 | 是 | 是 |
GET | /api/groups/{id} | 获取指定群组 | 是 | 是 |
POST | /api/groups | 创建一个群组 | 否 | 否 |
PUT | /api/groups/{id} | 更新群组所有信息 | 是 | 否 |
PATCH | /api/groups/{id} | 更新群组部分信息 | 是 | 否 |
DELETE | /api/groups/{id} | 删除指定群组 | 是 | 否 |
GET | /api/groups/{id}/members | 获取指定群组下的成员 | 是 | 是 |
GET | /api/groups/{id}/members/{memberId} | 获取指定群组下的指定成员 | 是 | 是 |
幂等性:同一个RESTful接口的多次访问,得到的资源状态是相同的。
安全性:对该RESTful接口访问,不会使服务端资源的状态发生改变。
规范建议
1. API尽量采用通过安全通道的HTTPS协议(https)。
2. 请求体与响应体统一通过json格式来承载,json使用Camel的命名规则,媒体类型需设置为“application/json”。
示例:
Request
Accept: application/json
Content-Type: application/json
Response
Content-Type: application/json
3. 请求体与响应体统一采用UTF-8编码格式,时间统一使用UTC格式:yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'。
4. URI模版:/{domain}/{service or module}/api/{version}/{resource},URI应全为小写字母,短语单词使用“-”分隔。
名称 | 说明 | 示例 |
domain | 领域名称,不需要区分领域时,可以不指定 |
education(教育领域) finance(金融领域) game(游戏领域) |
service or module | 服务或模块名 |
account(账户模块) order(订单服务) storage(库存服务) |
version | 版本号 |
v1 v2 v3 |
resource | 服务或模块内资源 |
users(用户) products(产品) members(成员) |
5. 资源增、删、改、查外的操作,采用模板:/{domain}/{service or module}/api/{version}/{resource}/action/{action}。
示例:/common/account/api/v1/users/action/login
响应消息建议
1. 获取资源列表成功返回,响应消息体中包含记录总条数、当前页码、每页记录,以及对应的资源。
示例:
Response Body
{
"total": xxx,
"pageIndex": xxx,
"pageSize":xxx,
"records":[
{ "id": xxx, "name":"xxx" },
{ "id": xxx, "name":"xxx" }
]
}
2. 获取指定资源成功返回200,响应消息体中包含该资源的信息。
3. 创建资源成功返回,并在响应消息头中包含定位该资源的地址。
示例:
Response Headers
{
"pragma": "no-cache",
"server": "xxx",
"content-type": "application/json; charset=utf-8",
"location": "https://xxx/api/users/xxx", //资源访问地址
"content-length": "xxx"
}
4. 资源更新成功返回,并在响应消息中体返回更新后的资源内容。
5. 资源删除成功返回,响应消息体无内容。
6. 针对400 Bad Request客户端错误,可以在响应消息体中扩展状态码。
示例:
Response Code
401 Bad Request
Response Body
{
"code": 400001,
"message": "用户名或密码错误"
}
----------------------------------------------------------
Response Code
401 Bad Request
Response Body
{
"code": 400002,
"message": "邮箱已存在"
}
----------------------------------------------------------
Response Code
401 Bad Request
Response Body
{
"code": 400003,
"message": "邮箱地址错误"
}
7. 针对5XX的服务端错误,只在响应消息体中提供简单提示,不可打印错误日志信息。
示例:
Response Body
{
"message": "内部错误,请稍后再试或联系管理员"
}
7. 其他客户端错误的响应码,只在响应消息体中提供相应提示。
示例:
Response Code
401 Unauthorized
Response Body
{
"message": "用户未登录"
}
----------------------------------------------------------
Response Code
403 Forbidden
Response Body
{
"message": "权限不足"
}
----------------------------------------------------------
Response Code
404 Not Found
Response Body
{
"message": "请求资源不存在或已被删除"
}
常见响应码
响应码 | 说明 |
200 OK | 请求已成功 |
201 Created | 资源已创建 |
204 No Content | 请求已成功,但无返回内容 |
304 Not Modified | 缓存有效 |
400 Bad Request | 语义有误,当前请求无法被服务器理解,请求参数错误 |
401 Unauthorized | 当前请求需要用户认证(登录) |
403 Forbidden | 用户已认证(登录),但权限不足 |
404 Not Found | 请求源未在服务器上被发现 |
405 Method Not Allowed | 请求方法不能被用于请求相应的资源,如使用PUT方法访问只接受POST方法的API |
500 Internal Server Error | 服务端内部错误 |
502 Bad Gateway | 网关错误 |
504 Gateway Timeout | 网关超时 |
RESTful规范建议的更多相关文章
- restful 规范(建议)
需求:开发cmdb,对用户进行管理. 做前后端分离,后端写api(URL),对用户表进行增删改查,应该写四个URL(还要给文档(返回值,返回,请求成功,干嘛,失败,干嘛)),然后分别写视图函数. ht ...
- RESTful 规范
RESTful 规范 前言 rest 是一种软件架构风格,如果使用的是 rest 接口,那么就可以说你的接口是 restful. rest接口是围绕''资源''展开的,利用 HTTP 的协议,其实 r ...
- DjangoRestFramework 学习之restful规范 APIview 解析器组件 Postman等
DjangoRestFramework学习一之restful规范.APIview.解析器组件.Postman等 本节目录 一 预备知识 二 restful规范 三 DRF的APIView和解析器组件 ...
- Django restful 规范
一.REST Frame Work REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为"表征状态转移&q ...
- django rest framework restful 规范
内容回顾: . django请求生命周期 -> 执行遵循wsgi协议的模块(socket服务端) -> 中间件(路由匹配) -> 视图函数(业务处理:ORM.模板渲染) -> ...
- day89 DjangoRsetFramework学习---restful规范,解析器组件,Postman等
DjangoRsetFramework学习---restful规范,解析器组件,Postman等 本节目录 一 预备知识 二 restful规范 三 DRF的APIView和解析 ...
- 18.DjangoRestFramework学习一之restful规范、APIview、解析器组件、Postman等
一 预备知识 预备知识:django的CBV和FBV CBV(class based view):多用,简单回顾一下 FBV(function based view): CBV模式的简单操作:来个登陆 ...
- day 87 DjangoRestFramework学习一之restful规范、APIview、解析器组件、Postman等
DjangoRestFramework学习一之restful规范.APIview.解析器组件.Postman等 本节目录 一 预备知识 二 restful规范 三 DRF的APIView和解析器组 ...
- 01 drf源码剖析之restful规范
01 restful规范 目录 01 restful规范 1. 什么是restful规范 2.restful规范详细 1. 什么是restful规范 restful是一套规则,是程序间进行数据传输的一 ...
随机推荐
- (NO.00003)iOS游戏简单的机器人投射游戏成形记(十六)
回到MainScene.m中添加selectRobot方法: -(void)selectRobot:(Robot *)robot{ LevelRestrict *lr = [LevelRestrict ...
- 将Ext JS 6应用程序导入Web项目
由于Ext JS 6包含了Sencha Touch,因而在应用程序结构有了些改变,Ext JS 5的方法已经不适用于新版本了.经过研究,发现6导入Web项目要比5简单. 下面来说说导入的过程. 使用S ...
- Socket编程实践(7) --Socket-Class封装(改进版v2)
本篇博客定义一套用于TCP通信比较实用/好用Socket类库(运用C++封装的思想,将socket API尽量封装的好用与实用), 从开发出Socket库的第一个版本以来, 作者不知道做了多少改进, ...
- 强力推荐各位攻城狮查看,收藏IT职业技能图谱(全套13张)
汇集整理泛 IT 技术领域(云计算,大数据,运维,安全,开发语言,智能硬件等)学习技能图谱,帮助程序员梳理知识框架结构,并尝试提供路径指导和精华资源,方便技术人学习成长. 运维工程师必备技能 程序开发 ...
- Coco2dx制作一个3D旋转的效果
建了工程之后修改HelloWorldScene.cpp文件,修改部分为 // on "init" you need to initialize your instance bool ...
- 运行React-Native项目
首先需要配置好环境.集体配置安装Homebrew,Node.js,React Native; 命令行开启RN项目 (如要cd 进入到当前项目的跟目录下) 1. npm install 2. react ...
- 跨平台移动APP开发进阶(四)AngularJS简介
AngularJS 是一个为动态WEB应用设计的结构框架.它能让你使用HTML作为模板语言,通过扩展HTML的语法,让你能更清楚.简洁地构建你的应用组件. 它的创新点在于,利用 数据绑定 和 依赖注入 ...
- MySQL学习笔记_10_MySQL高级操作(下)
MySQL高级操作(下) 五.MySQL预处理语句 1.设置预处理stmt,传递一个数据作为where的判断条件 prepare stmt from "select * from table ...
- 《java入门》第一季之类(String类字符串一旦被赋值就没法改变)
毫无疑问,String类是java里面最重要的类之一.因此它有很多方法需要了解和掌握. 字符串一旦被赋值,值就不能发生改变: package cn.itcast_02; /* * 字符串的特点:一旦被 ...
- C语言中sizeof与strlen区别
本文转载自:http://www.2cto.com/kf/201109/105100.html 1. 以字符串形式出现的,编译器都会为该字符串自动添加一个0作为结束符,如在代码中写"abc& ...