Restful API 接口设计规范

原创 已于 2022-11-09 16:20:02 修改 · 898 阅读 · 0 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
标签
#restful #设计规范 #后端
于 2022-11-01 15:51:34 首次发布
本文介绍了RESTful API的设计理念与规范，包括资源的概念、统一接口原则及常见HTTP方法的应用。通过实例展示了如何使用GET、POST、PUT、PATCH和DELETE等方法进行资源的获取、创建、更新和删除。

引言：

##  Restful API是根据REST架构原则设计的接口规范，由这个接口规范倡导的命名规范以及请求规范。

涉及知识点：

REST架构

 

  • 由  ↓   创立：

  • “一切皆资源”为前提：资源可以是一个图片、音乐、一个XML格式、HTML格式或者JSON格式等网络上的一个实体，除了一些二进制的资源外普通的文本资源更多以JSON为载体、面向用户的一组数据(通常从数据库中查询而得到)

  • 统一接口: 对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断 。

1. 概念

Restful APIRESTful是目前最流行的接口设计规范，基于HTTP请求开发；

官网地址：Reqres - A hosted REST-API ready to respond to your AJAX requestsA hosted REST-API ready to respond to your AJAX requestshttps://reqres.in/

2. request url规范

/api/资源?id=请求参数

***资源解释：

一般代表资源都是以复数的形式出现，但也有例外，如果是表示一些动作如登录、注册则不需要写成复数

3.  restful api 实例

   

RequestResponse
请求方式注释 (en)请求url请求参数注释 (zh)返回状态;返回数据
GETLIST USERS/api/users?page=2获取用户列表200 
{
    "page": 2,
    "per_page": 6,
    "total": 12,
    "total_pages": 2,
    "data": [
        {
            "id": 7,
            "email": "michael.lawson@reqres.in",
            "first_name": "Michael",
            "last_name": "Lawson",
            "avatar": "https://reqres.in/img/faces/7-image.jpg"
        },
        {
            "id": 8,
            "email": "lindsay.ferguson@reqres.in",
            "first_name": "Lindsay",
            "last_name": "Ferguson",
            "avatar": "https://reqres.in/img/faces/8-image.jpg"
        },
        {
            "id": 9,
            "email": "tobias.funke@reqres.in",
            "first_name": "Tobias",
            "last_name": "Funke",
            "avatar": "https://reqres.in/img/faces/9-image.jpg"
        },
        {
            "id": 10,
            "email": "byron.fields@reqres.in",
            "first_name": "Byron",
            "last_name": "Fields",
            "avatar": "https://reqres.in/img/faces/10-image.jpg"
        },
        {
            "id": 11,
            "email": "george.edwards@reqres.in",
            "first_name": "George",
            "last_name": "Edwards",
            "avatar": "https://reqres.in/img/faces/11-image.jpg"
        },
        {
            "id": 12,
            "email": "rachel.howell@reqres.in",
            "first_name": "Rachel",
            "last_name": "Howell",
            "avatar": "https://reqres.in/img/faces/12-image.jpg"
        }
    ],
    "support": {
        "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}
GETSINGLE USER/api/users/2获取用户详情200 
{
    "data": {
        "id": 2,
        "email": "janet.weaver@reqres.in",
        "first_name": "Janet",
        "last_name": "Weaver",
        "avatar": "https://reqres.in/img/faces/2-image.jpg"
    },
    "support": {
        "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}
GET SINGLE USER NOT FOUND/api/users/23用户不存在404 
{}
GETLIST <RESOURCE>/api/unknown200 
{
    "page": 1,
    "per_page": 6,
    "total": 12,
    "total_pages": 2,
    "data": [
        {
            "id": 1,
            "name": "cerulean",
            "year": 2000,
            "color": "#98B2D1",
            "pantone_value": "15-4020"
        },
        {
            "id": 2,
            "name": "fuchsia rose",
            "year": 2001,
            "color": "#C74375",
            "pantone_value": "17-2031"
        },
        {
            "id": 3,
            "name": "true red",
            "year": 2002,
            "color": "#BF1932",
            "pantone_value": "19-1664"
        },
        {
            "id": 4,
            "name": "aqua sky",
            "year": 2003,
            "color": "#7BC4C4",
            "pantone_value": "14-4811"
        },
        {
            "id": 5,
            "name": "tigerlily",
            "year": 2004,
            "color": "#E2583E",
            "pantone_value": "17-1456"
        },
        {
            "id": 6,
            "name": "blue turquoise",
            "year": 2005,
            "color": "#53B0AE",
            "pantone_value": "15-5217"
        }
    ],
    "support": {
        "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}
GETSINGLE <RESOURCE>api/unknown/2200 
{
    "data": {
        "id": 2,
        "name": "fuchsia rose",
        "year": 2001,
        "color": "#C74375",
        "pantone_value": "17-2031"
    },
    "support": {
        "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}
GETSINGLE <RESOURCE> NOT FOUND
/api/unknown/23		404{}
POSTCREATE
/api/users		 
{
    "name": "morpheus",
    "job": "leader"
}
创建用户201 
{
    "name": "morpheus",
    "job": "leader",
    "id": "473",
    "createdAt": "2022-11-01T07:35:54.844Z"
}
PUTUPDATE/api/users/2 
{
    "name": "morpheus",
    "job": "zion resident"
}
修改用户200 
{
    "name": "morpheus",
    "job": "zion resident",
    "updatedAt": "2022-11-01T07:38:34.189Z"
}
PATCHUPDATE/api/users/2 
{
    "name": "morpheus",
    "job": "zion resident"
}
修改用户200 
{
    "name": "morpheus",
    "job": "zion resident",
    "updatedAt": "2022-11-01T07:40:25.996Z"
}
DELETEDELETE/api/users/2删除用户204
POSTREGISTER - SUCCESSFUL/api/register 
{
    "email": "eve.holt@reqres.in",
    "password": "pistol"
}
注册用户成功200 
{
    "id": 4,
    "token": "QpwL5tke4Pnpja7X4"
}
POSTREGISTER - UNSUCCESSFUL/api/register 
{
    "email": "sydney@fife"
}
注册用户失败400 
{
    "error": "Missing password"
}
POSTLOGIN - SUCCESSFUL/api/login 
{
    "email": "eve.holt@reqres.in",
    "password": "cityslicka"
}
用户登录成功200 
{
    "token": "QpwL5tke4Pnpja7X4"
}
POSTLOGIN - UNSUCCESSFUL/api/login 
{
    "email": "peter@klaven"
}
用户登录失败400 
{
    "error": "Missing password"
}
GETDELAYED RESPONSE/api/users?delay=3200 
{
    "page": 1,
    "per_page": 6,
    "total": 12,
    "total_pages": 2,
    "data": [
        {
            "id": 1,
            "email": "george.bluth@reqres.in",
            "first_name": "George",
            "last_name": "Bluth",
            "avatar": "https://reqres.in/img/faces/1-image.jpg"
        },
        {
            "id": 2,
            "email": "janet.weaver@reqres.in",
            "first_name": "Janet",
            "last_name": "Weaver",
            "avatar": "https://reqres.in/img/faces/2-image.jpg"
        },
        {
            "id": 3,
            "email": "emma.wong@reqres.in",
            "first_name": "Emma",
            "last_name": "Wong",
            "avatar": "https://reqres.in/img/faces/3-image.jpg"
        },
        {
            "id": 4,
            "email": "eve.holt@reqres.in",
            "first_name": "Eve",
            "last_name": "Holt",
            "avatar": "https://reqres.in/img/faces/4-image.jpg"
        },
        {
            "id": 5,
            "email": "charles.morris@reqres.in",
            "first_name": "Charles",
            "last_name": "Morris",
            "avatar": "https://reqres.in/img/faces/5-image.jpg"
        },
        {
            "id": 6,
            "email": "tracey.ramos@reqres.in",
            "first_name": "Tracey",
            "last_name": "Ramos",
            "avatar": "https://reqres.in/img/faces/6-image.jpg"
        }
    ],
    "support": {
        "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests",
        "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
    }
}

restful 接口开发规范（RESTfulAPIdesignguide）
02-01
开发restful接口应该遵循统一的规范，保持规范的统一才能方便维护和应用
前端必看！RESTful API接口设计规范与最佳实践
小白菜的博客
05-26 770
在前端开发的世界里，与后端进行数据交互是非常重要的一环。RESTful API就是一种广泛使用的接口设计风格，它能够让前端和后端之间的通信更加高效、规范。本文的目的就是帮助前端开发者深入理解RESTful API的设计规范和最佳实践，范围涵盖了从基础概念到实际项目应用的各个方面。本文首先会介绍RESTful API的核心概念，通过有趣的故事和生活实例来帮助大家理解。接着会讲解核心概念之间的关系，并用示意图和流程图进行展示。然后会深入探讨核心算法原理和具体操作步骤，给出数学模型和公式。
RESTful接口API设计规范
kenabove的专栏
11-01 1万+
最近需要使用RESTful的软件架构风格编写webapi接口，参考很多RESTful文档，认识RESTful的接口规范，特此作下笔记。
RESTful API 设计规范
最新发布
总结分享
05-07 886
文章摘要： 本文介绍了RESTful API设计规范的核心概念与最佳实践。重点包括：1）资源URI设计应使用名词复数且避免动词；2）统一JSON响应格式；3）正确使用HTTP方法（GET查询、POST创建、PUT更新、DELETE删除）；4）幂等性处理方案；5）规范化的状态码使用；6）API版本控制策略。通过清晰的示例对比常见错误与正确写法，帮助开发者设计出更规范、易维护的API接口。文章强调RESTful风格的核心是资源导向和无状态交互，旨在降低前后端协作成本。
C#调用RESTful API
tanzhangwen的专栏
08-08 2万+
现在很多的网络服务都用RESTful API来实现。比如百度的搜索推广API介绍使用Rest原因：REST+JSON风格的API相比SOAP+XML，好处是：调用更加灵活，也更容易扩展；JSON格式传输信息比XML减少约30%的数据量，效率更高。因此建议开发者使用REST风格的API。查找了很多调用Rest API网络碎片资料，总是无法理解或者生效。下面摘一点觉得有效果的作为参考吧。http://w
Restful API思路
alashan007的博客
11-08 1599
1.通过服务器重写规则，将所有请求走一个入口方法，例如index.php的run()方法。 2.通过$_SERVER,找到请求方法，请求路径，请求参数，进行初始化参数 3.根据请求路径，走不同model处理，根据请求方法不同，走不同的处理方法。 4.补充，可以封装错误和异常处理，提前定义好允许的请求方法，等等。 以下为补充材料 https://blog.csdn.net/lmseo...
Restful API规范
00后的程序员
01-07 3万+
RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。该数据可用于数据类型，这些数据类型是指有关资源的操作的读取、更新、创建和删除。（也称为 RESTful Web 服务或 REST API）基于表示(REST)，它是。
RESTful API接口设计规范
2501_90226218的博客
01-18 834
把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级API，具备更高的灵活性，同时又能很容易的实现页面级的API功能。data:[简单来说就是url地址中只包含名词表示资源，使用http动词表示动作进行操作资源下面几个例子：左边是错误的设计，而右边是正确的。
[API接口设计] RESTful 规范
popstarqq的博客
03-20 5798
RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计；REST它是 Representational State Transfer的简称，中文的含义是: "表征状态转移" 或 "表现层状态转化" 1 发展来源和必要性 RESTful API 设计由 Roy Fielding 博士在其 2000 年的博士论文中定义。后来经过社区以及互联网发展的趋势需要就慢慢成为了一个标准； 目前我们实现一个RESTful接口，可以在web端 pc端及移动端，实现多...
RESTful API接口设计标准及规范；
热门推荐
时光偏执的博客
01-12 28万+
RESTful发展背景及简介 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 REST（Representational Stat...
Restful API 接口规范
LMGD的博客
04-23 2万+
Restful API 介绍 1）REST：英文representational state transfer直译为表现层状态转移，或者表述性状态转移；Rest 是web服务的一种架构风格，一种设计风格，是一种思想；同时Rest不是针对某一种编程语言的。 2）Restful(又名Rest):用URL定位资源、用HTTP动词（GET、POST、PUT、DELETE)描述操作、用HTTP STATUS/CODE定义操作结果。 以webService为例通俗解释 非Rest设计，以往我们都会..
Restful API 的接口规范
zhoupenghui168的博客
02-11 2万+
发展背景及简介 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 rest是Representational State Transfer三个单词的缩写，由Roy Fielding于2000年论文中提出的一种web软件结构风格，注意它仅仅只是代表着一种风格，并不代表着约束、标准。基
HTTP规范 RESTful API设计
2401_88238893的博客
05-06 4915
获取资源：创建资源：更新完整资源：部分更新资源：删除资源。
RESTful api
qq_40407998的博客
10-28 3204
官网 https://restfulapi.cn/ REST 是 Representational State Transfer的缩写，如果一个架构符合REST原则，就称它为RESTful架构 使用原因：RESTful 架构可以充分的利用 HTTP 协议的各种功能，是 HTTP 协议的最佳实践 RESTful API 是一种软件架构风格、设计风格，可以让软件更加清晰，更简洁，更有层次，可维护性更好 API 请求 1. HTTP 动词 GET： 读取（Read） POST： 新建（Create） PUT
Restful接口规范
weixin_43880061的博客
07-26 4312
注一般提倡用资源的复数形式，在url链接中奖励不要出现操作资源的动词，错误示范https//api.baidu.com/delete-user。-路飞的接口https//api.luffycity.com/api/v1/course/free/-https//api.baidu.com/books/1-delete请求删除主键为1的书。limit=10指定返回记录的数量。-https//api.baidu.com/books/1-get请求获取主键为1的书。...
RESTful接口设计规范
浮游的博客
05-26 6398
RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计。从字面可以看出，他是Rest式的接口，所以我们先了解下什么是Rest。REST与技术无关，它代表的是一种软件架构风格，REST它是 Representational State Transfer的简称，中文的含义是: “表征状态转移” 或 “表现层状态转化”。它是基于HTTP、URI、XML、JSON等标准和协议，支持轻量级、跨平台、跨语言的架构设计。
RESTful API简介、实战及其Demo（C#）分享
magicchz的博客
06-03 6583
RESTFUL（REST，Rpresentational State Transfer）是一种特定架构风格的接口规范，采用HTTP做传输协议。它不限于某一种开发语言，C#、java等都可以实现。
RESTful API 编写指南
06-10 484
基于一些不错的RESTful开发组件，可以快速的开发出不错的RESTful API，但如果不了解开发规范的、健壮的RESTful API的基本面，即便优秀的RESTful...
Restful API接口规范
a2398936046的博客
05-14 4万+
简介 REST：英文representational state transfer直译为表现层状态转移，或者表述性状态转移；Rest是web服务的一种架构风格，一种设计风格，是一种思想；同时Rest不是针对某一种编程语言的。 以webService为例通俗解释。 非Rest设计，以往我们都会这么写： http://localhost:8080/admin/getUser（查询用户） http://localhost:8080/admin/addUser（新增用户） http://localh..
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值