RESTful API接口设计规范

简介: 近年来移动互联网的发展,前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…),因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信,于是RESTful诞生了,它可以通过一套统一的接口为 Web,iOS和Android提供服务。

一、RESTful的诞生背景


近年来移动互联网的发展,前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…),因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信,于是RESTful诞生了,它可以通过一套统一的接口为 Web,iOS和Android提供服务。

20190629235933429.png


二、什么是RESTful?


RESTful,简称REST。

1、英文:Representational State Transfer。

2、直译:表现层状态转化。

3、本质:用URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作。

4、特点:RESTful是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。 基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

5、设计原则和约束条件:

5.1、网络上的所有事物都可以被抽象为资源(resource);

5.2、每一个资源都有唯一的资源标识(resource identifier),对资源的操作不会改变这些标识;

5.3、所有的操作都是无状态的。

凡事满足这些约束条件和原则的应用程序或设计就是 RESTful。

6、通俗解释:服务器上每一种资源,比如一个文件,一张图片,一部电影,都有对应的唯一的url地址(URI:统一资源标识符),如果我们的客户端需要对服务器上的这个资源进行操作,就需要通过http协议(GET、POST、PUT、PATCH、DELETE)执行相应的动作来操作它,比如进行获取,更新,删除。

7、补充:

7.1、 在 RPC 样式的架构中,关注点在于方法,而在 REST 样式的架构中,关注点在于资源 —— 将使用标准方法检索并操作信息片段(使用表示的形式)。资源表示形式在表示形式中使用超链接互联。

7.2、关于http接口、api接口、RPC接口、RMI、webservice、Restful等概念


三、Restful API接口设计规范


REST描述的是在网络中client和server的一种交互形式;REST本身不实用,实用的是如何设计 RESTful API(REST风格的网络接口)。

下面是根据Restful思想设计的通用规范:


3.1、协议

包含 http 和 https,使用 https 可以确保交互数据的传输安全。


3.2、路径规则|域名

路径又称 “终点”(endpoint),表示 API 的具体网址。

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

包含两种形式:

a、主域名:https://api.example.com

b、子目录:https://example.org/api/


3.3、版本控制

版本号:v {n} n 代表版本号,分为整形和浮点型

整型:大功能版本发布形式;具有当前版本状态下的所有 API 接口,例如:v1,v2。

浮点型:为小版本号,只具备补充 api 的功能,其他 api 都默认调用对应大版本号的 api 例如:v1.1 v2.2。

放入位置:

1、将版本号放入URL中(方便直观)。

2、将版本号放在请求头。


3.4、请求类型

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

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

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

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

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


3.5、传入参数

3.5.1、地址栏参数

主要用于过滤查询

a、restful 地址栏参数 /api/v1/product/122 122 为产品编号,获取产品为 122 的信息

b、get 方式的查询字串,此种方式主要用于过滤查询,如下:


?limit=10:指定返回记录的数量

?offset=10:指定返回记录的开始位置。

?page=2&per_page=100:指定第几页,以及每页的记录数。

?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序(sequence、order)。

?producy_type=1:指定筛选条件


3.5.2、请求body数据

主要用于提交新建数据


3.5.3、请求头

用于存放请求格式信息、版本号、token 密钥、语言等信息


{
    Accept: 'application/json',     //json格式
    version: 'v1.0'                       //版本号
    Authorization: 'Bearer {access_token}',   //认证token
    language: 'zh'                      //语言
}


3.6、返回格式

默认返回格式:


{
    code: 0,                         //状态码
    msg: 'ok',                       //提示信息
    data: {}                          //主体数据
}


使用 json 格式作为响应格式,状态码分为两种:

a、statusCode: 系统状态码,用于处理响应状态,与 http 状态码保持一致,如:200 表示请求成功,500 表示服务器错误。

b、code:业务状态码,用于处理业务状态,一般 0 标识正常,可根据需求自行设计错误码对照表,参考

20190630003422219.png


四、非 Restful Api 的需求


我们一般以 Restful Api 作为接口规范,但是由于实际业务开展过程中,可能会出现各种的 api 不是简单的 restful 规范能实现的,因此,需要有一些 api 突破 restful 规范原则。特别是移动互联网的 api 设计,更需要有一些特定的 api 来优化数据请求的交互。


4.1、单例型:

客户端根据需求分别请求对应 Api 接口,在客户端完成组装。

这种模式服务端相对简单,接口复用率高。

每个接口作用单一,如一个 App 首页,可能有轮播图、分类、推荐商品,则需要分别请求:


{
    code: 0,                         //状态码
    msg: 'ok',                       //提示信息
    data: {}                          //主体数据
}


开发过程中可根据实际需要结合使用。


4.2、组合型:

服务端组装数据,然后返回。

把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据,如:


api/v1/get-home-data 返回首页用到的所有数据

1

这类 API 有一个非常不好的地址,只要业务需求变动,这个 api 就需要跟着变更。


4.3、自定义组合API

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端,服务端根据请求内容,一次性把所有数据合并返回,相比于页面级API,具备更高的灵活性,同时又能很容易的实现页面级的API功能。


data:[
    {url:'api1',type:'get',data:{...}},
    {url:'api2',type:'get',data:{...}},
    {url:'api3',type:'get',data:{...}},
    {url:'api4',type:'get',data:{...}}
]


总结:

简单来说就是url地址中只包含名词表示资源,使用http动词表示动作进行操作资源.

下面几个例子:左边是错误的设计,而右边是正确的

GET /blog/getArticles --> GET /blog/Articles  获取所有文章
GET /blog/addArticles --> POST /blog/Articles  添加一篇文章
GET /blog/editArticles --> PUT /blog/Articles  修改一篇文章 
GET /rest/api/deleteArticles?id=1 --> DELETE /blog/Articles/1  删除一篇文章

参考链接:

1、RESTful(百科)

2、网上整理的对于Rest和Restful api的理解

3、什么是RESTful API

4、API 接口设计规范

5、系统API接口规范


相关文章
|
7天前
|
SQL 缓存 测试技术
构建高性能RESTful API:最佳实践与避坑指南###
—— 本文深入探讨了构建高性能RESTful API的关键技术要点,从设计原则、状态码使用、版本控制到安全性考虑,旨在为开发者提供一套全面的最佳实践框架。通过避免常见的设计陷阱,本文将指导你如何优化API性能,提升用户体验,确保系统的稳定性和可扩展性。 ###
44 12
|
4天前
|
JSON JavaScript API
深入浅出Node.js:从零开始构建RESTful API
【10月更文挑战第39天】 在数字化时代的浪潮中,API(应用程序编程接口)已成为连接不同软件应用的桥梁。本文将带领读者从零基础出发,逐步深入Node.js的世界,最终实现一个功能完备的RESTful API。通过实践,我们将探索如何利用Node.js的异步特性和强大的生态系统来构建高效、可扩展的服务。准备好迎接代码和概念的碰撞,一起解锁后端开发的新篇章。
|
7天前
|
存储 API 开发者
深入理解RESTful API设计原则
本文探讨了RESTful API的设计原则,强调了其在现代Web服务中的重要性。通过分析状态表示转移(REST)的概念、核心约束以及最佳实践,本文旨在为开发者提供构建高效、可扩展和易于维护的API的指导。文章还讨论了常见的设计陷阱和如何避免它们,以确保API设计的健壮性和灵活性。
|
9天前
|
JSON 缓存 API
构建高效RESTful API的最佳实践
【10月更文挑战第34天】在数字时代的浪潮中,后端开发扮演着至关重要的角色。本文将带你深入探索如何构建高效的RESTful API,从设计原则到实际编码技巧,再到性能优化和错误处理,我们将一一解锁这些技能。你将学会如何打造一个既优雅又强大的后端服务,让你的应用程序在激烈的市场竞争中脱颖而出。那么,让我们一起踏上这段精彩的旅程吧!
24 2
|
10天前
|
XML JSON API
【PHP开发专栏】PHP RESTful API设计与开发
随着互联网技术的发展,前后端分离成为Web开发的主流模式。本文介绍RESTful API的基本概念、设计原则及在PHP中的实现方法。RESTful API是一种轻量级、无状态的接口设计风格,通过HTTP方法(GET、POST、PUT、DELETE)操作资源,使用JSON或XML格式传输数据。在PHP中,通过定义路由、创建控制器、处理HTTP请求和响应等步骤实现RESTful API,并强调了安全性的重要性。
17 2
|
12天前
|
存储 安全 API
深入理解RESTful API设计原则
本文旨在探讨RESTful API设计的基本原则和最佳实践,帮助开发者构建高效、可维护的Web服务。通过分析REST架构的核心概念,如资源、统一接口、无状态通信等,本文将指导读者如何设计符合REST原则的API,以及如何处理常见的设计挑战,如版本控制、错误处理和安全性问题。
|
8天前
|
JavaScript 前端开发 NoSQL
深入浅出:使用Node.js构建RESTful API
【10月更文挑战第35天】在数字时代的浪潮中,后端技术如同海洋中稳固的灯塔,为前端应用提供数据和逻辑支撑。本文旨在通过浅显易懂的方式,带领读者了解如何利用Node.js这一强大的后端平台,搭建一个高效、可靠的RESTful API。我们将从基础概念入手,逐步深入到代码实践,最终实现一个简单的API示例。这不仅是对技术的探索,也是对知识传递方式的一次创新尝试。让我们一起启航,探索Node.js的奥秘,解锁后端开发的无限可能。
|
JSON API PHP
CI中如何保护RESTful API
步骤5 保护RESTful API   为了保护RESTful API,可以在application/config/rest.php中设置安全保护级别,如下所示: $config['rest_auth'] = 'basic';    其中保护级别有如下设置:   None:任何人都...
940 0
|
5天前
|
JSON API 数据格式
淘宝 / 天猫官方商品 / 订单订单 API 接口丨商品上传接口对接步骤
要对接淘宝/天猫官方商品或订单API,需先注册淘宝开放平台账号,创建应用获取App Key和App Secret。之后,详细阅读API文档,了解接口功能及权限要求,编写认证、构建请求、发送请求和处理响应的代码。最后,在沙箱环境中测试与调试,确保API调用的正确性和稳定性。
|
17天前
|
供应链 数据挖掘 API
电商API接口介绍——sku接口概述
商品SKU(Stock Keeping Unit)接口是电商API接口中的一种,专门用于获取商品的SKU信息。SKU是库存量单位,用于区分同一商品的不同规格、颜色、尺寸等属性。通过商品SKU接口,开发者可以获取商品的SKU列表、SKU属性、库存数量等详细信息。

热门文章

最新文章