1、RESTful发展背景及简介

网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)。因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。

REST(Representational State Transfer)表述性状态转换,REST指的是一组架构约束条件和原则。 如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。

2、RESTful设计风格

2.1、推荐格式

1)url格式:

http(s)://server.com/api-name/{version}/{domain}/{rest-convention}

这里,{version}代表api的版本信息。{domain}是一个你可以用来定义任何技术的区域(例如:安全-允许指定的用户可以访问这个区域。)或者业务上的区域(例如:同样的功能在同一个前缀之下。)。{rest-convention} 代表这个域(domain)下,约定的rest接口集合。

2)参数格式:

GET采用两种常见格式:

① URL参数(更推荐),如:

https://www.example.com/v1.1?name=‘lk-abc%’&age=’lt-10’

②路径参数,如:

https://www.example.com/v1.1/employees/{id}

POST采用两种常见格式:

①Json格式包装参数提交

POST  https://www.example.com/v1.1
Content-Type: application/json;charset=utf-8
{"title":"test","sub":[1,2,3]}

②form表单参数提交

POST   https://www.example.com/v1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
title=test&sub%5B%5D=1&sub%5B%5D=2&sub%5B%5D=3

3)返回体格式:

{"status”: 200,
"message”:"用户查询返回成功”,
“document”:”https://www.example.com/doc#userinfo”,
   "data”: {
       "className”: "com.fiberhome.smartas.pricecloud.User”,
        "id”:“1b434wtert564564sdffey32”,
        "name”: "lilei",
        "age”: 18,
        "job”: {
             "className”:"com.fiberhome.smartas.pricecloud.Job”,
            "id”: “1b434wtert564564sdffeyey”,
            "name”: “微服务架构师”
        }
    }
}

2.2、协议

考虑到服务的安全性,建议使用https作为API的通信协议,当然http也是可以的。

2.3、域名

建议将API部署在专有域名下,以此屏蔽消费者对服务提供方的部署细节(可借助于平台的反向代理+路由网关),在服务地图丰富起来之后可以考虑多级域名。

https://api.example.com
https://example.org/api/

2.4、版本

考虑到微服务的平滑升级,可以将API的版本号放入URL,也可以将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。

https://api.example.com/v1/

2.5、复数名词路径

在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

https://api.example.com/v1/employees

2.6、http协议类型表达资源操作

HTTP协议里的8种方法,及其他衍生方法,常用的Get、post可以间接的实现其余所有的操作,根据框架和浏览器的兼容性选择性使用。

1)  GET(SELECT):从服务器取出资源(一项或多项)。

2)  POST(CREATE):在服务器新建一个资源。

3)  PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。

4)  PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。

5)  DELETE(DELETE):从服务器删除资源

6)  HEAD:获取资源的元数据。

7)  OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

8)  TRACE:回显服务器收到的请求,主要用于测试或诊断。

9)  CONNECT:HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。

10) MOVE: 请求服务器将指定的页面移至另一个网络地址。

11) COPY: 请求服务器将指定的页面拷贝至另一个网络地址。

12) LINK: 请求服务器建立链接关系。

13) UNLINK: 断开链接关系。

14) WRAPPED: 允许客户端发送经过封装的请求。

15) Extension-mothed:在不改动协议的前提下,可增加另外的方法。

GET  https://api.example.com/v1/employees/ 获取所有雇员

2.7、过滤信息

请求信息应该为集合提供过滤、排序、选择和分页等功能

1)Filtering过滤:

使用唯一的查询参数进行过滤:

GET /cars?color=red 返回红色的cars

2)Sorting排序:

允许针对多个字段排序

GET /cars?sort=-manufactorer,+model

这是返回根据生产者降序和模型升序排列的car集合

3)Fieldselection

移动端能够显示其中一些字段,它们其实不需要一个资源的所有字段,给API消费者一个选择字段的能力,这会降低网络流量,提高API可用性。

GET /cars?fields=manufacturer,model,id,color

4)Paging分页

使用 limit 和offset.实现分页,缺省limit=20 和offset=0;

GET /cars?offset=10&limit=5

为了将总数发给客户端,使用订制的HTTP头:X-Total-Count.

链接到下一页或上一页可以在HTTP头的link规定,遵循Link规定:

Link:<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>;rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>;rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>;rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>;rel="prev",

2.8、返回结果为统一的json格式

一方面,出于平台标准化的API管理,另一方面,遵循微服务的宽进严出设计理念,建议RESTful采用标准的Json格式。

返回结构体

{   
  "className”: "com.fiberhome.smartas.pricecloud.User”,
    "id”:“1b434wtert564564sdffey32”,
    "name”: "lilei",
    "age”: 18,
    "job”: {
             "className”:"com.fiberhome.smartas.pricecloud.Job”,
            "id”: “1b434wtert564564sdffeyey”,
            "name”: “微服务架构师”
     }
}
Object implements Serializable;
JSONObject.fromObject(json);
JSONObject.parseObject(text)

2.9、返回结果应该包含状态码

常见状态码

1)  200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。

2)  201 CREATED -[POST/PUT/PATCH]:用户新建或修改数据成功。

3)  202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)

4)  204 NO CONTENT - [DELETE]:用户删除数据成功。

5)  400 INVALID REQUEST -[POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。

6)  401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。

7)  403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。

8)  404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。

9)  406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。

10)  410Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。

11)  422Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。

12)  500INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

2.10、返回结果中提供帮助链接

RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。注:Github就是这么做的

返回体结构

{"link":
{
 "document":" https://www.example.com/docs#zoos",
 "href":"https://api.example.com/zoos",
 "title":"List of zoos",
 "type":"application/vnd.yourformat+json"
}
}

2.11、API扩展事项

1)RESTful API依托PaaS平台治理,需要对API进行认证、授权、参数加密等操作,可考虑在HTTP头部加认证token、调用链指令、状态信息等系列信息。
     2)如PPT所言,API分层,会有内部API和外部API之分,两种API的设计或有不同(甚至是不同协议)。
     3)对于API设计的状态选择,建议为无状态、N次幂等,但后续或存在性能优化问题,http2.0待评测。

微服务RESTful 接口设计规范的更多相关文章

  1. 轻量级容器Docker+微服务+RESTful API

    [宗师]李锟(44035001) 10:23:03感觉Docker这样的轻量级容器+微服务+RESTful API三者可以形成一个铁三角.这也代表了PaaS未来的发展方向. [宗师]李锟(440350 ...

  2. restful接口设计规范总结

    这篇 文章主要是借鉴他人,但是自己很想总结出一套规范,以供向我这样的新手使用,用来规范代码,如果有什么好的提议,请不吝赐教,本篇文章长期更新! 一.重要概念: REST,即Representation ...

  3. restFul接口设计规范

    1.域名 1 应该尽量将API部署在专用域名之下. https://api.example.com 2 如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下. https://example. ...

  4. 聊一聊 Spring Boot 中 RESTful 接口设计规范

    在设计接口时,有很多因素要考虑,如接口的业务定位,接口的安全性,接口的可扩展性.接口的稳定性.接口的跨域性.接口的协议规则.接口的路径规则.接口单一原则.接口过滤和接口组合等诸多因素,本篇文章将简要分 ...

  5. 无规矩不成方圆,聊一聊 Spring Boot 中 RESTful 接口设计规范

    在设计接口时,有很多因素要考虑,如接口的业务定位,接口的安全性,接口的可扩展性.接口的稳定性.接口的跨域性.接口的协议规则.接口的路径规则.接口单一原则.接口过滤和接口组合等诸多因素,本篇文章将简要分 ...

  6. restFul接口设计规范[仅供参考]

    域名 应该尽量将API部署在专用域名之下. https://api.example.com 如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下. https://www.example.or ...

  7. RESTful 接口设计规范

    get 用来获取,post 用来新建(也可以用于更新),put 用来更新,delete 用来删除.

  8. 微服务接口设计(RESTful规范)

    微服务的接口设计(RESTful规范) 基本知识 URI:在RESTful架构中,每个URI代表一种资源 URI规范: 不用大写 用中杠-,不用下划线_ 路径中不能有动词,只能有名词 名词表示资源集合 ...

  9. spring boot / cloud (十四) 微服务间远程服务调用的认证和鉴权的思考和设计,以及restFul风格的url匹配拦截方法

    spring boot / cloud (十四) 微服务间远程服务调用的认证和鉴权的思考和设计,以及restFul风格的url匹配拦截方法 前言 本篇接着<spring boot / cloud ...

随机推荐

  1. fastclick插件学习(一)之用法

    原理 在检测到touchend事件后, 会通过dom自定义事件模拟一个click事件,并把浏览器300ms之后真正触发的点击事件屏蔽掉,fastclick是不会对PC浏览器添加监听事件 使用 1.引入 ...

  2. sip呼叫里SDP的一些字段的含义

    v=0 o=- 1 0 IN IP4 164.135.25.51 #local ip ,即本机SIP信令交互地址 s=SNS call #用于传递会话主题 c=IN IP4 164.135.25.51 ...

  3. c++容易混淆知识点

    C ++令人困惑的知识点1 函数传递指针和传递引用之间的区别? 1 GT;指针定义可能未初始化,但引用不可能; 2 - ;引用只能与一个实体组合,指针可以与多个实体组合; 3 GT;加法和减法的含义是 ...

  4. .NET 反射应用

    object request = null; string requestObjClassName = "命名空间" + 类型.ToString(); Type type = Ty ...

  5. Java并发编程之线程池及示例

    1.Executor 线程池顶级接口.定义方法,void execute(Runnable).方法是用于处理任务的一个服务方法.调用者提供Runnable 接口的实现,线程池通过线程执行这个 Runn ...

  6. 8.Mapper动态代理

    在前面例子中自定义 Dao 接口实现类时发现一个问题:Dao 的实现类其实并没有干什么 实质性的工作, 它仅仅就是通过 SqlSession 的相关 API 定位到映射文件 mapper 中相应 id ...

  7. Win10系统升级更新方式将会更智能

    使用Win10系统的你肯定遇到过在工作时开始自动更新而不得不搁置工作的情况,想必你也已经被Win10系统的自动更新折磨不已,不过这种情况将会马上得到改观. 微软现在已经开始寻找更智能的版本升级更新方式 ...

  8. 前端基础(十):Bootstrap Switch 选择框开关控制

    简介 Bootstrap Switch是一款轻量级插件,可以给选择框设置类似于开关的样式 它是依赖于Bootstrap的一款插件 下载 下载地址 在线引用 导入 因为它是依赖于Bootstrap的一款 ...

  9. IDEA中使用git报错Permission denied (publickey)

    最近在使用idea开发时,使用git拉取远程仓库的代码时,报错Permission denied (publickey),原因是因为ssh的密钥失效,必须得重新设置下ssh的密钥即可. 命令很简单,在 ...

  10. drone 更新仓库为truested

    drone 更新仓库为truested drone repo update -trusted=true my_org/repository DRONE_USER_CREATE=username:oct ...