Restful API 的设计规范(转)
1. URI
URI 表示资源,资源一般对应服务器端领域模型中的实体类。
URI规范
不用大写;
用中杠
-
而不用下杠_
;参数列表要encode;
URI中的名词表示资源集合,使用复数形式;
资源集合与单个资源
资源集合:
/zoos //所有动物园
/zoos/1/animals //id为1的动物园内的所有动物
单个资源:
/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1,2,3的动物园
2. Request
HTTP方法
通过标准HTTP方法对资源CRUD:
GET: 查询
GET /zoos
GET /zoos/1
GET /zoos/1/employees
POST: 创建单个资源。POST一般向“资源集合”型URI发起;··· javaascipt
POST /animals //新增动物
POST /zoos/1/employees //id为1的动物园的所有员工
PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH 负责部分更新,客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起
PUT /animals/1
PUT /zoos/1
DELETE:删除
DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals //删除id为1的动物园内的所有动物
HEAD / OPTION 用的不多,就不多解释了。
安全性与幂等性
安全性:不会改变资源状态,可以理解为只读的;
幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。
安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。
3. Response
不要包装
response 的 body 直接就是数据,不要做多余的包装。错误示例:
{
"success":true,
"data":{"id":1,"name":"xiaotuan"},
}
各HTTP方法成功处理后的数据格式:
json格式的约定:
时间用长整形(毫秒数),客户端自己按需解析(moment.js)
不传null
字段
分页response
{
"paging":{"limit":10,"offset":0,"total":729},
"data":[{},{},{}...]
}
7. API演进
版本
常见的三种方式:
在uri中放版本信息:
GET /v1/users/1
Accept Header:
Accept: application/json+v1
自定义 Header:
X-Api-Version: 1
用第一种,虽然没有那么优雅,但最明显最方便。
URI失效
随着系统发展,总有一些API失效或者迁移,对失效的API,返回404 not found 或 410 gone;对迁移的API,返回 301 重定向。
来源:
Restful API 的设计规范(转)的更多相关文章
- Restful API 的设计规范
RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计.降低开发的复杂性,提高系统的可伸缩性. Restful API接口规范包括以下部分: 一.协议 API与用户的通信协议, ...
- Restful API的设计规范
原文:https://blog.csdn.net/u013063153/article/details/72828164 本文总结了 RESTful API 设计相关的一些原则,只覆盖了常见的场景.有 ...
- Restful API设计规范及实战
Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14) 的产品是否存在(话说我还是很喜欢玩类似 ...
- Restful API设计规范及实战【说的比较清楚了】
Restful API设计规范及实战 Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14 ...
- RESTful API设计的点
RESTful API 前言 一直在使用RESTful API,但是好像概念还是很模糊的,总结下使用到的点 设计的规范 协议 API与用户的通信协议,总是使用HTTPs协议. 域名 应该尽量将API部 ...
- rest-framework 序列化格式Restful API设计规范
理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...
- RESTful api 设计规范
该仓库整理了目前比较流行的 RESTful api 设计规范,为了方便讨论规范带来的问题及争议,现把该文档托管于 Github,欢迎大家补充!! Table of Contents RESTful A ...
- PHPer的项目RESTful API设计规范是怎样的?
RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 什么是RESTful RESTful是一种软件设计风格, 主要用于客户端与服务端交互的软件. 一般来说RESTful ...
- 理解 RESTful API 设计规范
RESTful是目前最流行的API设计规范,它是用于Web数据接口的设计.从字面可以看出,他是Rest式的接口,所以我们先了解下什么是Rest. REST与技术无关,它代表的是一种软件架构风格,RES ...
随机推荐
- vs2010下sort比较函数链接错误问题
环境:win7 + vs2010 + C++ 实现vector的sort算法,在类的头文件中写入比较函数时会出现链接错误: error LNK2005: "bool __cdecl comp ...
- net mvc中angular
把angular项目整合到.net mvc中 之前的开发选择的是完全舍弃服务端,仅保留最简单web服务器提供angular经打包的静态资源,此外所有的业务与数据请求都访问一个分离的WebApi来实 ...
- 配置免SSH
在要远程登录别人的服务器中生成授权标识:ssh-keygen -t rsa上传至需被免登录的服务器:scp ~/.ssh/id_rsa.pub root@xx.xx.xx.xx:/root/.ssh/ ...
- 使用URLEncoder、URLDecoder进行URL参数的转码与解码
1. import java.net.URLDecoder; import java.net.URLEncoder; String strTest = "?=abc?中%1&2< ...
- Oracle - 数据库巡检脚本
分享一个oracle数据库巡检脚本,欢迎大家使用,希望大家在用的过程中发现脚本中的错误并提出改进意见. -- 数据库巡检脚本 -- 版本号2.1 -- 该脚本仅对数据库的做一个初步的巡检,具体的优化方 ...
- vue打包以及在Apache环境下的配置
vue打包,我们都清楚,实在记不住命令的可以去package.json中看: npm run build 打包后会生成dist文件夹,将dist文件夹下的所有文件复制到Apache下的www的文件夹下 ...
- ApiPost的环境变量的定义和使用「ApiPost环境变量」
新版的ApiPost(Chrome拓展V2.0.8+/客户端V2.2.1+)已经支持环境变量的定义和使用. 本文主要介绍ApiPost环境变量的第一课:如何定义环境变量,并如何使用它. ApiPost ...
- 洛谷T21778 过年
题目描述 有 n(1 \leq n \leq 10^5)n(1≤n≤105) 个小朋友,过年了,要发放 m(1 \leq m \leq 10^5)m(1≤m≤105) 次礼物. 每次发放,会给出三个参 ...
- Xtreme9.0 - Communities 强连通
Xtreme9.0 - Communities 题目连接: https://www.hackerrank.com/contests/ieeextreme-challenges/challenges/c ...
- springMvc Velocity tool 源码分析
在公司使用pandoraboot配置了velocity tool,一直不明白官方支持的init方法没有调用,而且不支持velocity tool 1.x版本的定义(1.x和2.x的定义见下面),而另一 ...