知识分享之规范——RESTful API规范 背景 知识分享之规范类别是我进行整理的日常开发使用的各类规范说明，作为一个程序员需要天天和各种各样的规范打交道，而有些规范可能我们并不是特别了解，为此我将一些常见的规范均整理到知识分享之规范系列中...符合 REST 架构风格的 Web API（或 Web 服务）是 REST API。...5.分层系统 REST 允许您使用分层系统架构，例如，在服务器 A 上部署 API，在服务器 B 上存储数据并在服务器 C 中验证请求。客户端通常无法判断它是直接连接到终端服务器还是中间连接。.../devices/{id}/configurations/{id} 请注意，这些URI 不使用任何动词或操作。...日常我们进行各种各样的增删改查，规范中推荐如下HTTP请求方式进行提供相关接口： GET 查询、POST创建、PUT更新、DELETE删除、 REST API 使用HTTP 响应消息的状态行部分来通知客户端其请求的总体结果
什么是RESTful API ? RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。...RESTful API设计规范 既然了解了RESTful的一些规则和特性，那么具体该怎么去设计一个RESTful API呢？...接受JSON格式的响应：Accept: application/json发送JSON格式的请求体：Content-Type: application/jsonURI书写规范 在RESTful API设计中...以下是一些关于URI书写的常见规范：使用小写字母： 建议使用小写字母，因为URI是区分大小写的。。...案例 详情请见：https://restfulapi.cn/总结 RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则
RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计 http请求方法 RESTful API 设计规范 关于「能愿动词」的使用 为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下...://example.com/api/* 如果你的应用很庞大或者你预计它将会变的很庞大，那 应该 将 API 放到子域下（api.example.com）。...你 必须 在引入新版本 API 的同时确保旧版本 API 仍然可用。...status=closed：指定筛选条件 所有 URL 参数 必须 是全小写，必须 使用下划线类型的参数形式。...分页参数 必须 固定为 page、 per_page 经常使用的、复杂的查询 应该 标签化，降低维护成本。如 GET /trades?
除了https的协议之外，能不能加上通用的一套算法以及规范来保证传输的安全性呢？...一般情况下接口最好使用https协议，如果使用http协议，Token机制只是一种减少被黑的可能性，其实只能防君子不能防小人。...API token，其中sign=加密(appId + timestamp + key) 客户端拿着api_token 去访问不需要登录就能访问的接口 当访问用户需要登录的接口时，客户端跳转到登录页面，...ApiCodeEnum /** * 错误码code可以使用纯数字,使用不同区间标识一类错误，也可以使用纯字符，也可以使用前缀+编号 * * 错误码：ERR + 编号 * * 可以使用日志级别的前缀作为错误类型区分...传统方式我们要在方法中访问某个变量，可以通过传参的形式往方法中传参，如果多个方法都要使用那么每个方法都要传参；如果使用ThreadLocal所有方法就不需要传该参数了，每个方法都可以通过ThreadLocal
API操作设计... 8 2.3.1. 资源型操作... 8 2.3.2. 业务型操作... 12 3. API 帮助文档规范... 12 3.1. 帮助文档内容规范... 12 3.2....概要 BAAS 平台上的所有 API，必须严格遵守本规范。 通过本文档规范 BAAS 平台所有向外提供 API，体现技术的统一性、规范性。...并使得所有 API 尽量靠近业界规范的同时，提高API的易用性、可读性、兼容性等，并方便平台的使用者更快地发现、熟悉所有API以供开发。...主要包含两个方面的规范：API 本身的设计规范、API 帮助文档的编写规范。 1.2. 参考资料 《Representational State Transfer (REST)》 1.3....API 设计规范 2.1.
API接口测试规范总结 目录 1、参数校验 2、返回值校验 3、命名规范 4、业务判断 5、安全校验 1、参数校验 1、正常场景 （1）功能按照接口规范要求实现 （2）返回状态码200 2、异常场景...直接为空 null [] {} （2）参数错误 （3）无操作权限 （4）特定的业务逻辑报错，涉及敏感的报错不应该有明确的原因，例如登录失败就不能报成密码错误或手机号码错误 （5）单位标准，时间，服务端使用时间戳还是直接日期类型...参数类型非法，例：int传string 必填参数数值范围错误，数值越界 必填参数为空格，前面，中间，尾部 （3）必填参数不传，必填参数全部为空，必填参数部分为空 （4）必填参数组合，有些参数需要配合一起使用时需组合测试...4、非必填参数 （1）接口文档规范要求非必传的参数 （2）正向，所有参数均传正确 （3）逆向 某个参数为空，需要做判空处理 非必填参数少传一个，接收方需要处理 5、升级接口 （1）什么情况下需要升级接口...接口、字段命名的含义准确且拼写无误 4、业务判断 1、约束条件 （1）数值限制，例如：规定达到什么数值才能被使用，未达到不可以使用 （2）状态限制，例如：删除状态的数据不可被其他业务关联 （3）关系限制
概述 这篇文章分享 API 接口设计规范，目的是提供给研发人员做参考。 规范是死的，人是活的，希望自己定的规范，不要被打脸。...platform 平台 iOS、Android system 系统 ios 13.3、android 9 device 设备型号 iPhone XR、小米9 udid 设备唯一标示 apiVersion API...安全规范 敏感参数加密处理 登录密码、支付密码，需加密后传输，建议使用 非对称加密。 其他规范 参数命名规范 建议使用驼峰命名，首字母小写。 requestId 建议携带唯一标示追踪问题。...其他规范 属性名命名时，建议使用驼峰命名，首字母小写。 属性值为空时，严格按类型返回默认值。 金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。...签名设计 签名验证没有确定的规范，自己制定就行，可以选择使用 对称加密、 非对称加密、 单向散列加密 等，分享下原来写的签名验证，供参考。
作者：马一特 cnblogs.com/mayite/p/9798913.html RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。...本文总结 RESTful 的设计细节，介绍如何设计出易于理解和使用的 API。...客户端发出的数据+操作指令都是“动词+宾语”的结构，比如GET /articles这个命令，GET是动词，/articles是宾语，动词通常就有5种HTTP请求方法，对应CRUD操作，根据 HTTP 规范...为了统一起见，建议都使用复数 URL，比如GET /articles/2要好于GET /article/2。...", "detail": { "surname": "This field is required." } } 提供链接 API 的使用者未必知道，URL 是怎么设计的。
RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。...RESTFUL特点包括： 1、每一个URI代表1种资源； 2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源...在当前流行的前后端分离架构，人们发现原来这套用于超文本传输的协议是如此适合用于设计基于互联网的api接口，基于http动词以及标准的http status返回信息，能够非常好地描述api的特性，并且可读性非常好...接口，实现对这张图片的删除操作，这个api应该怎么设计？...除了HTTP METHOD,rest另外一套重要的规范就是HTTP STATUS，这套状态码规范定义了常规的api操作所可能产生的各种可能结果的描述，遵循这套规范，会使得你的api变得更加可读，同时也便于各种网络
返回结果 针对不同操作，服务器向用户返回的结果应该符合以下规范。...良好的文档 文档应该是规范的API的重要的组成部分，没有文档的API是难以给他人使用的，也是不利于维护的。...改框架为创建JSON或YAML格式的RESTful API 文档提供了OpenAPI规范。swagger文档可由各种编程语言处理，可以在软件开发周期中嵌入源代码控制系统中，以便进行版本管理。...总结 这一篇主要介绍了RESTful API以及如何使用swagger编写规范的RESTful API。.../ 如何编写基于OpenAPI规范的API文档：https://www.gitbook.com/book/huangwenchao/swagger/details 使用 Swagger 文档化和定义 RESTful
本文作者：IMWeb 梁伟盛 原文出处：IMWeb社区 未经同意，禁止转载 RESTful API 规范 v1.0 [toc] URI URI规范 不要用大写 单词间使用下划线'_' 不使用动词...，资源要使用名词复数形式，如：user、rooms、tickets 层级 >= 三层，则使用'?'...Method GET 非id的参数使用'?'...第三个层次（Level 2）的 Web 服务使用不同的 HTTP 方法来进行不同的操作，并且使用 HTTP 状态码来表示不同的结果。...第四个层次（Level 3）的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。
在日常开发中，一个优雅的API，必须提供简单明了的响应值，然后根据状态码就可以大概知道问题的所在。这里主要整理一下HTTP状态码和自定义状态码。...今后任何新的请求都应使用新的URI代替。 302 临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI。 303 查看其它地址。与301类似。使用GET和POST请求查看。...305 使用代理。所请求的资源必须通过代理访问。 400 客户端请求的语法错误，服务器无法理解。 401 用户身份认证失败。 402 保留，将来使用。...3、自定义响应状态码规范 后端返回给前端一般使用json格式，定义如下： { #返回状态码 Code:integer, #返回信息描述 message:string,...return new Result(resultStatus, data); } } 3.4、返回体测试 @RestController @RequestMapping("/api
前言 越来越多的Web应用程序使用JSON作为API的一种数据交换格式进行交互。本文档的目标是使HTTP JSON API的设计风格保持一致，容易被理解和维护。...URL规范 URL代表所提供的API的唯一性和永久性，在此之前我们应该[SHOULD]设计合理的URL： 必须[MUST]全部使用小写字母拼写URL // good http://www.example.com...orderBy=name 必须[MUST]使用破折号 – // good http://www.example.com/api/v1/user-info // bad http://www.example.com.../api/v1/user_info 破坏性行为(create，delete，update)必须[MUST]使用POST方法 // good POST http://www.example.com/api...id=123 建议[RECOMMENDED]使用容易理解的英文单词 // good POST http://www.example.com/api/v1/user/list // bad GET http
URI规范 不用大写; 用中杠-而不用下杠_; 参数列表要encode; URI中的名词表示资源集合，使用复数形式; 资源集合与单个资源 资源集合： /zoos //所有动物园 /zoos...Bookmarker 经常使用的、复杂的查询标签化，降低维护成本。 如： GET /trades?...对第三点的实现稍微多说一点： Java 服务器端一般用异常表示 RESTful API 的错误。API 可能抛出两类异常：业务异常和非业务异常。...常用的http状态码及使用场景： ? ---- 5. 服务型资源 除了资源简单的CRUD，服务器端经常还会提供其他服务，这些服务无法直接用上面提到的URI映射。...URI失效 随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301 重定向。
接口签名 接口签名是一种常见的安全措施，用于确保API请求的完整性和身份验证。...接口签名机制能够有效地防止API请求被篡改，确保数据的安全性和请求的合法性。不过，它不提供加密通信的功能，因此对于敏感信息的传输，还需要结合使用加密技术。...SM4算法加/解密算法的结构相同，只是使用轮密钥相反，其中解密轮密钥是加密轮密钥的逆序。...格式建议 以下是一些建议，用于确保API响应格式的统一性： 明确的版本号：在响应中包含API版本号，这样在API更新时可以保持向后兼容性。...通过以上措施，可以确保API接口的响应格式统一、清晰，并且易于客户端开发者使用和集成。
RESTful是目前比较流行的接口路径设计规范，基于HTTP，一般使用JSON方式定义，通过不同HttpMethod来定义对应接口的资源动作，如：新增（POST）、删除（DELETE）、更新（PUT、PATCH...路径设计 在RESTful设计规范内，每一个接口被认为是一个资源请求，下面我们针对每一种资源类型来看下API路径设计。...路径设计的注意事项如下所示： 资源名使用复数 资源名使用名词 路径内不带特殊字符 避免多级URL 新增资源 请求方式 示例路径 POST https://api.yuqiyu.com/v1/users.../v1/users/{id} 更新单个资源的全部元素 PATCH https://api.yuqiyu.com/v1/users/{id} 更新单个资源的部分元素 在更新资源数据时使用PUT方式比较多...timestamp 请求响应的时间戳 总结 RESTful是API的设计规范，并不是所有的接口都应该遵循这一套规范来设计，不过我们在设计初期更应该规范性，这样我们在后期阅读代码时根据路径以及请求方式就可以了解接口的主要完成的工作
站在业务角度，有一些指导原则，指导我们完善 Open API 机制： 前端页面使用的接口和 Open API 提供的接口是同一套接口 任意的前端页面接口都应该有对应的 Open API 站在技术角度，有很多的...本文将围绕诸多因素，尝试探讨出一份合适的 Open API 开放规范。 Open API 设计考虑因素 一个完善的 Open API 规范到底应该规范哪些东西？...有如下的指导原则： 有复杂业务逻辑的 API ，无法使用简单的增、删、改、查描述时宜使用 RPC 风格。...总结一下 RPC 风格的优势： API 设计难度较低，容易落地 阿里云大多数成熟的 IAAS 层产品使用 RPC 规范 适合复杂业务场景 一个详细的 RPC 接口文档示例 创建服务 请求参数 序号 字段中文名...命名规范 API 应使用拼写正确的英文，符合语法规范，包括单复数、时态和语言习惯 不能出现多个含义相近但功能无实际差别的 API，如同时存在 /user/getUser 和 /user/describeUser
本文作者：IMWeb 梁伟盛 原文出处：IMWeb社区 未经同意，禁止转载 RESTful API 规范 v1.0 [toc] URI URI规范 不要用大写 单词间使用下划线'_' 不使用动词...，资源要使用名词复数形式，如：user、rooms、tickets 层级 >= 三层，则使用'?'...GET 非id的参数使用'?'...第三个层次（Level 2）的 Web 服务使用不同的 HTTP 方法来进行不同的操作，并且使用 HTTP 状态码来表示不同的结果。...第四个层次（Level 3）的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。
2.接口规范(restful) RESTful（Representational State Transfer）是目前较为流行的Web API 的设计规范，特点：简单、易上手。...用api关键字标识接口url： https://api.baidu.com https://www.baidu.com/api 注：看到api代表该请求url链接是完成前后台数据交互的。...://api.baidu.com/delete-user 特殊的接口可以出现动词，因为这些接口一般没有一个明确的资源，或是动词就是接口的核心含义 https://api.baidu.com/place...handler = self.http_method_not_allowed return handler(request, *args, **kwargs) 4.使用...5.Pycharm debug窗口的使用 5.1 操作步骤： 5.1.1添加断点：直接在标记处点击鼠标左键即可。
image.png 现在在开发中前后端都是分离开发，后端提供接口给前台，RESTful 架构，就是目前最流行的一种互联网软件架构，也相当于是接口规范 关于「能愿动词」的使用 为了避免歧义，文档大量使用了...协议 客户端在通过 API 与后端服务通信的过程中，应该 使用 HTTPS 协议 域名 API 应该部署在专用域名之下，应尽可能保持足够简单。...，必须 遵守 HTTP 设计规范，必须 选择合适的 HTTP 状态码。...目前常见返回错误信息的方法有两种： 将错误详细放入 HTTP 响应首部 直接放入响应实体中 建议参考 理解RESTful架构 RESTful API 设计指南 RESETful API 设计规范...原创文章采用CC BY-NC-SA 4.0协议进行许可，转载请注明：转载自：什么是RESETful API 设计规范？
领取专属 10元无门槛券
手把手带您无忧上云
