首页 > 其他分享 >什么是Restful风格的API

什么是Restful风格的API

时间:2024-09-13 18:46:59浏览次数:9  
标签:请求 GET API 风格 POST Restful 资源 客户端

 

1、REST的定义

  请参考论文:https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

2、API文档编写语义:
  本文档中的关键字:
  必须-MUST,
  不得-MUST NOT,
  必需-REQUIRED,
  应该-SHALL,
  不应该-SHALL NOT,
  应该-SHOULD,
  不应该-SHOULD NOT,
  推荐-RECOMMENDED,
  可能-MAY
  可选-OPTIONAL

3、请求类型定义
  请求类型(Method Type)根据业务动作进行合理选择,不能全都使用 POST 方式,如下:
  PUT:这个请求的含义就是推送某个资源到服务器,更新整个资源
  PATCH: 更新局部资源
  POST:向服务器提交一个全新且唯一的资源(无法幂等)
  DELETE:这个请求会删除服务端的某个资源
  GET:向服务器获取资源
  HEAD: 大的语义上和GET请求是类似,只是只需要返回响应头信息即可,通常用于客户端用于资源存在性等判断
  TRACE:这是一个将服务器所收到请求回显给客户端的请求,主要用于测试或诊断。
  OPTIONS:返回对于指定资源,可以使用的请求类型。这个方法在正常工作中使用的比较少,它一般用途是,在正式请求资源之前,先看看
对于资源都可以使用那些请求;
  CONNECT :请求HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。通常用于SSL加密服务器的链接


4、请求状态码
根据实际业务场景,严格规范定义并正确使用请求状态码,客户端的每一次请求, 服务器端必须给出回应,回应一般包括HTTP状态码 和 数据两部分
  1xx: 信息,请求收到了,继续处理。
  2xx: 代表成功. 行为被成功地接收、理解及采纳。
  3xx: 重定向。
  4xx: 客户端错误,请求包含语法错误或请求无法实现。
  5xx: 服务器端错误.
  2xx 状态码
    200 OK [GET]: 服务器端成功返回用户请求的数据。
    201 CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功。
    202 Accepted 表示一个请求已经进入后台排队(一般是异步任务)。
    204 NO CONTENT -[DELETE]: 用户删除数据成功。
  4xx 状态码
    400:Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误,服务器不理解客户端的请求,未做任何处理。
    401: Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)。
    403:Forbidden: 表示用户得到授权了,但是访问被禁止了, 也可以理解为不具有访问资源的权限。
    404:Not Found: 所请求的资源不存在,或不可用。
    405:Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
    406:Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式,但是只有XML格式)。
    410:Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的。
    415: Unsupported Media Type: 客户端要求的返回格式不支持,比如,API只能返回JSON格式,但是客户端要求返回XML格式。
    422:Unprocessable Entity: 客户端上传的附件无法处理,导致请求失败。
    429:Too Many Requests: 客户端的请求次数超过限额。
  5xx 状态码
    500:INTERNAL SERVER ERROR; 服务器发生错误。
    502:网关错误。
    503: Service Unavailable 服务器端当前无法处理请求。
    504:网关超时。

5、REST API的一些设计约束:   (1)、统一的设计风格,提供API可读性、适配性,不同开发人员之间可以无障碍通过API可以看到API背后的主干逻辑   (2)、单一职责,API设计尽量做一件事情,将能力原子化,后期扩展及对接提升复用性,这也是软件设计原则当中常常需要遵守的   (3)、资源封装,API 的设计是对封装好的资源的操作,而不是对数据库的操作   (4)、命名规范,合理命名访问地址以及参数,用于降低理解成本   (5)、版本控制,确保所有变化,不能影响原有调用方的正常运行,允许在API的URL当中出现版本描述,如: GET /users/v1(代表V1版本的API)   (6)、无状态化,API的语义不应该依赖服务端的状态,比如说依赖服务端时钟也不行,查最近1天的人数(比如现在的时间是2024-08-13 18:23:11),那么不能写:GET /users/lastday之类,只能写: GET /users?endTime={时间戳}   (7)、资源表述层次分明原则,如/xx业务/xx模块/xx资源,层次分明   (8)、API本身是可缓存的   (9)、API的URL当中不可以出现动词,而只能出现层次分明的名词   (10)、API的URL中使用复数进行命名,如:users   (11)、面向公众的服务,建议返回数据格式主JSON,尽管也可以是其它的方式,如XML, CSV等   (12)、允许URL当中出现过滤、排序、分页参数,如:GET /users?condition={condition}&sort={sort}&current={current}&size={size}   (13)、幂等性原则,除了POST之外,其它的都应该遵守幂等性原则,POST不能遵守是因为POST每次都是创建新的唯一性资源(它无法幂等)   (14)、完善的错误状态码描述       (15)、完善的API文档,最好能够完全符合OAS3.0规范   6、REST API的编写示范:   (1)、登录:POST /sessions,登录的本质就是创建一个会话       (2)、退出:DELETE /sessions/{token},退出登录的本质就是删除一个会话     (3)、注册:POST /registrations,注册的本质就是添加一个注册事件   (4)、转账:POST /transactions, 转账的本质就是新增一个交易   (5)、查询用户:GET  /users,直接查询用户列表   (6)、更新用户信息: PUT /users, 部分更新用户信息   7、REST API的最佳实践参考   https://www.bacancytechnology.com/blog/rest-api-best-practices   https://blog.iclouds.work/2020/09/01/api-design/paypal_api_style_guide            

标签:请求,GET,API,风格,POST,Restful,资源,客户端
From: https://www.cnblogs.com/lhrogerluo/p/18412698

相关文章

  • enrollmentapi.dll文件丢失导致程序无法运行问题
    其实很多用户玩单机游戏或者安装软件的时候就出现过这种问题,如果是新手第一时间会认为是软件或游戏出错了,其实并不是这样,其主要原因就是你电脑系统的该dll文件丢失了或没有安装一些系统软件平台所需要的动态链接库,这时你可以下载这个enrollmentapi.dll文件(挑选合适的版本文件)......
  • Java Script - Web Api
    变量声明有3个ver、let和const。建议const优先,其次为let。constarr=['red','pink']arr.push('blue')arr=[1,2,4]arr.push(5)//错误,arr为const1、WebApi基本认知1.1、作用和分类作用:就是使用j......
  • RESTful规范 GET请求、POST请求、PUT请求、DELETE请求的使用规范
    RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景,实现第三方OTT调用移动网络资源的功能,动作类型为新增、变更、删除所调用资源。RESTFul规范:一.http动词:GET(SELECT):从服务器取出资源......
  • Capital许可管理最佳实践
    Capital许可管理最佳实践:具体方法与案例引领企业走向合规与高效在数字化时代,软件已成为企业运营不可或缺的一部分,而Capital许可管理则是确保软件合规使用、优化成本和控制风险的关键。本文将结合具体实践方法和案例,为您详细介绍Capital许可管理的最佳实践。一、明确许可需求与策......
  • 【flask系列】基于flask的 RESTful API示例
    原创xlwin136人工智能教学实践RESTfulAPI(RepresentationalStateTransferApplicationProgrammingInterface)是一种基于REST架构风格的网络应用程序接口。REST是一种设计网络服务的架构风格,它通过使用HTTP协议的通用动词(如GET、POST、PUT、DELETE等)来允许客户端和......
  • Sentinel在边缘服务(如API网关)中的应用和策略是什么?
    在微服务架构中,API网关(也称为边缘服务)通常作为所有客户端请求的单一入口点。API网关不仅可以提供路由功能,还将安全性、监控、缓存、限流、动态数据转换等功能集中在一起。Sentinel在API网关中的应用主要是为了保护后端服务免受过载风险,确保系统的稳定性和响应时间。以下是......
  • 按图搜索的实时性:阿里巴巴拍立淘API返回值的快速响应
    阿里巴巴拍立淘API作为一种基于图像识别技术的搜索服务,其返回值的快速响应是其实时性的重要体现。以下是对阿里巴巴拍立淘API返回值的快速响应的详细解释,并包含代码示例。一、快速响应机制图像识别技术:阿里巴巴拍立淘API利用先进的图像识别技术,能够迅速分析用户上传的图片特征,并与......
  • 面试-JS Web API - 存储
    cookieHTML5存储(localStorage和sessionStorage)cookiecookie本身用于浏览器和server通讯的,被借用到本地存储来。可以用document.cookie来修改。同一个变量会覆盖,不同变量会追加。localStorage和sessionStorage//保存数据到localStoragelocalStorage.getItem('a......
  • 邮政EMS查询|通过python查询快递单号API
    快递聚合查询的优势1、高效整合多种快递信息。2、实时动态更新。3、自动化管理流程。聚合国内外1500家快递公司的物流信息查询服务,使用API接口查询邮政EMS物流的便捷步骤,首先选择专业的数据平台的快递API接口:https://www.tanshuapi.com/market/detail-68以下示例是参考的示例代码:im......
  • 面试-JS Web API-Linux命令
    关键Linux命令虽然前端开发者不需要掌握Linux的所有命令,但以下基本的命令对日常工作是非常有用的:文件和目录管理ls:列出当前目录下的文件和文件夹。lsls-l#显示详细信息ls-a#显示隐藏文件cd:切换目录。cd/path/to/directorycd..#返回上一级目录pwd:显......