云学堂RESTful API 请求头
Source
标识调用方的类别 (101,102,103,201,202...)
Token
标识当前操作者的身份
Content-Type
标识请求体内容格式 (application/json)
Origin
用于设定js跨域访问时允许的域名
REST式服务的优点 可以利用缓存Cache来提高响应速度 通讯本身的无状态性可以让不同的服务器的处理一系列请 求中的不同请求，提高服务器的扩展性
浏览器即可作为客户端，简化软件需求 相对于其他叠加在HTTP协议之上的机制，REST的软件依赖
性更小
不需要额外的资源发现机制 在软件技术演进中的长期的兼容性更好
HTTP方法 + URI API
POST+集合资源URI：在服务器新建一个资源。 GET+集合资源URI：从服务器取出资源列表。 GET+单个资源URI：在服务器取出特定资源。 PUT+单个资源URI：在服务器更新特定资源。 DELETE+单个资源URI：从服务器删除资源。
9e5d-8247e0f77a8c (唯一标识这个资源的id,不限于uuid)
从属关系
/v1/orgs/
/v1/orgs/1625fdcb-2f44-4949-9e5d8247e0f77a8c
/v1/orgs/1625fdcb-2f44-4949-9e5d8247e0f77a8c/users
REST式服务的特点 网络上的所有事物都被抽象为资源, 每个资源对应一个唯 一的资源标识URI
通过HTTP协议方法作连接器对资源进行操作 对资源的任何操作不改变资源标识URI 所有的服务器操作都是无状态的
议题
REST是什么 REST式服务的特点 REST式服务的优点 云学堂RESTful API
HTTPS更佳,条件限制时采用HTTP
域名
专用域名
版本
/v1/
URI
集合资源 /v1/orgs (英文单词复数) 单个资源 /v1/orgs/1625fdcb-2f44-4949-
码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但 是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录。 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无
法判断发出的请求是否成功。
HTTP/0.9
HTTP/1.1
RFC 2616
1991
1996.5
1997.1
2009
HTTP/2
RFC 7540
2015
HTTP/1.0
RFC 1945
SPDY
1.2、HTTP基础——版本演进（SSL/TLS）
NetScape设 计SSL 1.0，
但未发布
SSL 3.0版问世， 得到大规模应用
HTTP/2概述
HTTP/2概述
CONTENTS
PART 1 HTTP基础
PART 2 Http/2协议
PART 3 Http/2支持情况
PART 4 Http/2疑虑
HTTP基础
1.1 缩略语 1.2 版本演进 1.3 HTTP概述 1.4 HTTP现状与优化 1.5 安全相关
1.1、HTTP基础——缩略语
/v1/orgs/1625fdcb-2f44-4949-9e5d8247e0f77a8c/users/18ef1d08-803c-4f2c-a79e-a6edc839e5db
云学堂RESTful API HTTP方法
GET：获取（SELECT） POST：新建（CREATE） PUT：更新（UPDATE） DELETE：删除（DELETE）
响应体
HTTP方法为GET/POST时返回 具体定义需看API文档
云学堂RESTful API 出错时的响应
状态码
400~50X 具体参见API文档中的Error列表
响应体
格式 {
"error": { "key": "${errorKey}", "message": "${errorMsg}"
4 HTTPS：HTTP的安全版（HTTP over Secure Socket Layer)
5 SSL：安全套接层（Secure Sockets Layer） TLS：传输层安全协议（Transport Layer Security Protocol）
1.2、HTTP基础——版本演进（HTTP）
响应体
HTTP方法为GET/POST时返回 有Error时返回 具体定义需看 响应头
Location
HTTP方法为POST时返回 用来表示新创建的资源URI
Access-Control-Allow-Origin
跨域访问时设置允许的域名
OpenAPI 3.0 基础URL结构
JSON及其语法简介
JSON简介
JSON （JavaScript Object Natation）
一种轻量级的数据交换格式 和XML一样，基于纯文本的数据格式 可以表达String、Number、Boolean、数组、甚至对
象等数据 适合于服务器与JavaScript客户端的交互
数组表示 使用 [ ] 包含所有元素，每个元素用逗号分隔，元
素可以是任意的值。 比如:
[ "abc" , 123 , true, null ]
访问其中的元素，使用索引号，从 0 开始。
JSON基本语法
Object表示 用 { } 包含一系列无序的 Key-Value 键值对表示,
其中Key和Value之间用冒号分割，每个key-value之间 用逗号分割。
} } 具体参见API文档中的Error列表
OpenAPI 3.0
OpenAPI
定义：Open API即开放API,也称开放平台。 所谓的开放API （OpenAPI）是服务型网站常见的一种应用，网站的服务商将自 己的网站服务封装成一系列API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这 种行为就叫做开放网站的API，所开放的API就被称作OpenAPI （开放API）
User-agent
标识当前请求所用的操作系统和浏览器信息
X-FORWARDED-FOR
IIS服务器端调用RESTful API时需要传递客户端ip
云学堂RESTful API 请求参数
主要用于获取资源列表类型的API 排序
?order=email%20asc 参数值为字段名+%20+asc或desc
• 为实现更好的可重用性，对规范的整体架构进行了重构，重构后 的架构如下图所示。
• 支持 oneOf、anyOf 和 not 的 JSON 模式。 • 可使用模式的参数。 • 引入了 Cookie 参数，去除了 dataForm 参数。 • 具有自身实体的主体参数（Body Parameter）。 • 可协商的内容类型。 • 多主机支持。 • 简化了安全定义，改进的 WebHooks 不再通过回调机制描述。
JSON基本语法
JSON实际上基于JavaScript语法的一个子集。
值的表示
字符串、数值、true、false、null、Object或数组等。 字符串
"abc" 、 "\r\n" 、 "\u00A9"
数值
123 、 -123.5
布尔
true 、 false
null
JSON基本语法
一套简单的设计原则、一种架构风格(或模式)，不是一种 具体的标准或架构。
基于使用HTTP、URI等现有的广泛流行的协议和标准
对Web的本质回归，一种真实描述Web的方式
REST目的：寻找Web特性，然后使用这些特性来指导Web设 计
议题
REST是什么 REST式服务的特点 REST式服务的优点 云学堂RESTful API
规范目标：定义标准的、独立于语言的指向 REST API 的接口，使 得服务能力无需访问源代码、文档，或是借助于网络流量检查，就 可被人类和计算机发现并理解。通过对 OpenAPI 做适当定义后， 消费者可使用最小数量的实现逻辑理解远程服务，并与远程服务交 互。
新的 OpenAPI 规范 3.0 带来了如下重大改进
目录：
RESTful API简介 OpenAPI 3.0 JSON及其语法简介 HTTP/2概述
RESTful API简介
议题
REST是什么 REST式服务的特点 REST式服务的优点 云学堂RESTful API
REST是什么
REST(Representational State Transfer):表示性状态转 移，分布式超媒体软件的一种架构风格 --源自2000年Roy Thomas Fielding的博士论文。
比如: { "bookname":"Ajax基础",
"publisher":"电子工业出版社", "price": 56.0 } 访问其中的数据，通过obj.key来获取对应的value
JSON基本语法
复杂数据表示
Object或数组中的值还可以是另一个 Object 或 者数组 ，以表示更复杂的数据 比如: List list=new ArrayList(); List.add(emp) [ {"name":"张三", "age":18 , "loves":["看书","玩游戏"]}, {"name":"王五", "age": 20,"loves":["旅游"]} ]