东莞市盛裕绒艺玩具有限公司

东莞市盛裕绒艺玩具有限公司

易利GO备用线路

15196455002
联系方式
全国服务热线: 15196455002

咨询热线:15589891629
联系人:林昌毅
地址:福建省泉州市石狮市蚶江镇莲西村47号

REST API设计指导——译自Microsoft REST API Guidelines(一)

来源:易利GO备用线路   发布时间:2019-06-26   点击量:390

前言

前面我们说了,有章可循,有据可依,有正确的产品流程和规范,我们的工作才不至于产生混乱,团队的工作才能更有成效。我们经常见到,程序开发可能只用了半个月,但是接口的联调却经常需要花费半个月甚至一个月左右。

 

如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?这里我们不得不提到REST API。

 

另外,REST API的书籍很多,但是完整完善实践丰富的设计指导并不多见,我们有幸看到了微软团队的作品——Microsoft REST API Guidelines,因此才有了此篇内容。由于公众号文章内容字数有限,接下来我们会将翻译稿拆分并分享出来。翻译的不对之处,请多多指教。

 

什么是REST API?

Rest不是一种协议,也不是一种文字格式,更不是一种开发框架,它是一种系列的设计约束的集合:无状态性、将超媒体作为应用状态的引擎,这个约束我们统称Fielding约束。也就是说,它是一种软件架构风格、设计风格。它的两大核心理念是资源和表述,这个能加快我们对它的理解,然而REST -- REpresentational State Transfer,英语的直译就是“表现层状态转移”。

 

简单的来说,在REST API:URL定位资源,用HTTP动词(GET,POST,PUT,DELETE)描述操作。前面说了,REST 指的是一组架构约束条件和原则。那么满足这些约束条件和原则的应用程序或设计就是 RESTful。

 

为什么用REST API?

1.前后端分离主要以API为界做接洽的,这样就会有很多的API,API的表现力更强,更加便于理解。

2.REST API没有状态,不管前端是何种状态何种设备下都可以无差别的请求资源。

3.Restful API有直接的规范和原则。

 

简单的来说,有以下好处:

看到Url就知道可以拿到什么。

看到Http请求方法就知道要做什么。

看到Http状态码就知道干的怎么样了。

 

Microsoft REST API Guidelines目录

1 Abstract 摘要

2 Table of contents 目录表

3 Introduction 介绍

3.1 Recommended reading 推荐阅读

4 Interpreting the guidelines 解读指导 

4.1 Application of the guidelines 应用指导

4.2 Guidelines for existing services and versioning of services 现有服务指南和服务版本化

4.3 Requirements language 要求的语言

4.4 License 许可证

5 Taxonomy 分类 

5.1 Errors 错误

5.2 Faults 故障

5.3 Latency 潜在因素

5.4 Time to complete 完成时间

5.5 Long running API faults 长期运行的API故障

6 Client guidance 客户指导

6.1 Ignore rule 忽略规则

6.2 Variable order rule 变量排序规则

6.3 Silent fail rule 无声失效规则

7 Consistency fundamentals 一致性基础

7.1 URL structure 网址结构

7.2 URL length 网址长度

7.3 Canonical identifier 标准标识符

7.4 Supported methods 支持方法

7.5 Standard request headers 标准请求请求头

7.6 Standard response headers 响应请求头

7.7 Custom headers 自定义请求头

7.8 Specifying headers as query parameters 指定头部为查询参数

7.9 PII parameters PII参数

7.10 Response formats 响应格式

7.11 HTTP Status Codes HTTP状态码

7.12 Client library optional 可选的客户端库

8 CORS cors 

8.1 Client guidance 客户端指导

8.2 Service guidance 服务指导

9 Collections 集合 

9.1 Item keys 项的key

9.2 Serialization 序列化

9.3 Collection URL patterns 集合URL模式

9.4 Big collections 大集合

9.5 Changing collections 修改集合

9.6 Sorting collections 集合排序

9.7 Filtering 过滤

9.8 Pagination 分页

9.9 Compound collection operations 复合集合操作

10 Delta queries 增量查询

10.1 Delta links 增量链接

10.2 Entity representation 实体表示

10.3 Obtaining a delta link 获得增量链接

10.4 Contents of a delta link response 增量链接响应内容

10.5 Using a delta link 使用增量链接

11 JSON standardizations JSON标准化

11.1 JSON formatting standardization for primitive types 主要类型的JSON格式化标准化

11.2 Guidelines for dates and times 日期和时间指南

11.3 JSON serialization of dates and times 日期和时间的JSON序列化

11.4 Durations 持续时间

11.5 Intervals 间隔

11.6 Repeating intervals 重复间隔

12 Versioning 版本

12.1 Versioning formats 版本格式

12.2 When to version 版本的时间

12.3 Definition of a breaking change 非延续性更改的定义

13 Long running operations 长时间运行的操作

13.1 Resource based long running operations (RELO) 基于资源的长时间运行(RELO)

13.2 Stepwise long running operations 分步运行的长时间操作

13.3 Retention policy for operation results 操作结果保留策略

14 Push notifications via webhooks 通过webhooks推送通知

14.1 Scope 范围

14.2 Principles 原则

14.3 Types of subscriptions 订阅类型

14.4 Call sequences 调用序列

14.5 Verifying subscriptions 验证订阅

14.6 Receiving notifications 接收通知

14.7 Managing subscriptions programmatically programmatically订阅管理

14.8 Security 安全性

15 Unsupported requests 不支持的请求 

15.1 Essential guidance 基本指导

15.2 Feature allow list 特征允许列表

16 Naming guidelines 命名准则

16.1 Approach 途径

16.2 Casing 框架

16.3 Names to avoid 避免的命名

16.4 Forming compound names 规范的复合词

16.5 Identity properties 标识属性

16.6 Date and time properties 日期和时间属性

16.7 Name properties 属性名

16.8 Collections and counts 集合和计数

16.9 Common property names 共同属性命名

17 Appendix 附录

17.1 Sequence diagram notes 时序图注释

, 1, 0, 9);

相关产品

COPYRIGHTS©2017 易利GO备用线路 ALL RIGHTS RESERVED 备案号:390