HTTP API接口设计规范

简介: HTTP API接口设计规范

1. 所有请求使用POST方法

使用post,相对于get的query string,可以支持复杂类型的请求参数。例如日常项目中碰到get请求参数为数组类型的情况。


便于对请求和响应统一做签名、加密、日志等处理


2. URL规则

URL中只能含有英文,使用英文单词或简称,不要使用汉语拼音


所有字符使用小写字母


多个单词之前使用连字符-分隔,如third-login, 不要使用thirdlogin,thirdLogin或third_login


URL的path部分使用 系统/模块/操作 的格式,如 ims/video/list


系统,表示这个接口是微服务中的哪个服务,可使用简称

模块,表示系统的子模块。模块名字使用名词全称,且使用单数形式

操作,表示具体的接口,使用动词+名词的形式,需要考虑单复数。比如add-user,list-users,delete-users

3. HTTP头部

将具体业务无关的数据放在HTTP headers

后端系统可以在不涉及请求和响应体的情况下,处理一些公用逻辑

4. 请求和响应体

使用utf-8编码

JSON格式

如果需要加密,可以将正常的JSON加密后用base64编码

5. HTTP状态码

业务的处理结果不体现在http状态码,由响应体的错误码字段表示

只是有部分http状态码表示业务无关的响应,例如

200: 业务已处理,但是处理成功还是失败由响应体表示

400: 错误的请求,多用在请求参数验证。客户端开发要保证向服务器提交正确格式的请求

401: 认证失败,一般没有token或者没有token过期

403: 没有权限调用这个接口。客户端应该隐藏用户无权限的操作

500: 服务器异常

6. 字段命名

JSON来自javascript语言,所以字段命名遵循javascript语言,使用 lowerCamelCase 小骆驼拼写法

不要使用下划线链接的 snake_case

7. 数据类型

常用数据类型映射


bool:映射为 string,使用Y表示true,N表示false

int: 映射为number

long: 映射为string,因为js的number类型能处理的数值范围不够,实际项目中会导致各种奇怪的问题

float, double, decimal: 映射为string

日期、时间:映射为string

注意:


表示ID概念的字段,统一使用string

数据传输时,如果某个字段为空值,直接省略这个字段不传,减少网络开销

响应体业务数据包含多个数据结构时,优先使用嵌套格式,例如下面这个用户创建的消息

"item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",

8. 响应体格式

  • code 业务处理的错误码,使用简短的能够体现错误种类的英文单词表示,使用大写字母,使用下划线分隔单词。不建议用数字表示错误码,用数字表示需要额外维护错误码表。


    28.png



相关文章
|
25天前
|
缓存 监控 测试技术
接口设计的18条军规:打造高效、可靠的API
【10月更文挑战第2天】在软件开发中,接口设计是连接不同模块、系统乃至服务的桥梁。一个优秀的接口设计不仅能提升开发效率,还能确保系统的稳定性和可扩展性。以下是接口设计的18条军规,旨在帮助你在工作和学习中设计出更加高效、可靠的API。
56 1
|
4月前
|
安全 前端开发 API
ThinkPHP5 API模块开发规范与示例
【7月更文挑战第6天】本技术文档旨在指导开发者如何完全遵循ThinkPHP5框架的开发规范来构建RESTful API模块。ThinkPHP5(简称TP5)是一款基于PHP的轻量级MVC框架,其简洁、高效的特点非常适合快速开发Web应用及API接口。以下是创建API模块的基本步骤、最佳实践以及代码示例。
184 0
|
6月前
|
网络协议 JavaScript 安全
第十一篇 前沿趋势与展望:深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3
第十一篇 前沿趋势与展望:深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3
102 1
|
1月前
|
API
使用`System.Net.WebClient`类发送HTTP请求来调用阿里云短信API
使用`System.Net.WebClient`类发送HTTP请求来调用阿里云短信API
21 0
|
3月前
|
Oracle Java 关系型数据库
JDK版本特性问题之在 JDK 11 中,HTTP Client API 的特点有哪些
JDK版本特性问题之在 JDK 11 中,HTTP Client API 的特点有哪些
|
4月前
|
消息中间件 API 数据库
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
|
4月前
|
缓存 JSON 算法
http【详解】状态码,方法,接口设计 —— RestfuI API,头部 —— headers,缓存
http【详解】状态码,方法,接口设计 —— RestfuI API,头部 —— headers,缓存
62 0
|
5月前
|
存储 Java API
JavaSE——常用API进阶二(2/8)-BigDecimal(BigDecimal的常见构造器、常用方法,用法示例,使用规范)
JavaSE——常用API进阶二(2/8)-BigDecimal(BigDecimal的常见构造器、常用方法,用法示例,使用规范)
43 1
|
6月前
|
JSON 测试技术 API
Python的Api自动化测试使用HTTP客户端库发送请求
【4月更文挑战第18天】在Python中进行HTTP请求和API自动化测试有多个库可选:1) `requests`是最流行的选择,支持多种请求方法和内置JSON解析;2) `http.client`是标准库的一部分,适合需要低级别控制的用户;3) `urllib`提供URL操作,适用于复杂请求;4) `httpx`拥有类似`requests`的API,提供现代特性和异步支持。根据具体需求选择,如多数情况`requests`已足够。
74 3
|
7天前
|
供应链 数据挖掘 API
电商API接口介绍——sku接口概述
商品SKU(Stock Keeping Unit)接口是电商API接口中的一种,专门用于获取商品的SKU信息。SKU是库存量单位,用于区分同一商品的不同规格、颜色、尺寸等属性。通过商品SKU接口,开发者可以获取商品的SKU列表、SKU属性、库存数量等详细信息。