RESTful API风格

时间: 2019-06-19阅读: 205标签: api

任何对外提供服务的应用都绕不开API的发布,你的API可能是这个样子:

www.baidu.com/api/v1/getUsername?id=1
或者
www.baidu.com/app/index.php?r=info/user/getUsername&id=1

如果答案是YES,那么用句很潮的话,我们可以说你的API很不RESTful。


API风格

首先要说,不管你的API属于哪种风格,只要能够满足工作需要,就足够了。API格式并不存在绝对的标准,只存在不同的设计风格。

API设计包含两部分:请求和响应。
请求包含:请求URL、请求方法、请求头部信息等。
响应包含:响应体和响应头部信息。

一个请求URL的组成:

https://www.baidu.com:443/app/index.php?r=info/user/getUsername&id=1#tag
# 请求方法:GET
# 请求协议:protocal: https
# 请求端口:port: 443
# 请求域名:host: www.baidu.com
# 请求路径:pathname: /app/index.php
# 查询字符串:search: r=info/user/getUsername&id=1
# 页面书签:hash: #tag

根据URL组成部分:请求方法、请求路径和查询字符串,我们有几种常见的API风格。比如当删除id=1的作者编写的类别为2的所有文章时:

# 纯请求路径
GET www.baidu.com/articles/delete/authors/1/categories/2
# 一级使用路径,二级以后使用查询字符串
GET www.baidu.com/articles/delete/author/1?category=2
# 纯查询字符串
GET www.baidu.com/deleteArticles?author=1&category=2
# RESTful风格
DELETE www.baidu.com/articles?author=1&category=2

前面三种都是GET请求,主要的区别在于多个查询条件时怎么传递查询字符串,有的通过使用解析路径,有的通过解析传参,有的两者混用。同时在描述API功能时,可以使用article/delete,也可以使用deleteArticles。

而第四种RESTful API最大的区别在于行为动词DELETE的位置,不在url里,而在请求方法中。


RESTful设计风格

REST(Representational State Transfer 表现层状态转移)是一种软件架构风格、设计风格,而不是标准。主要用于客户端和服务端的API交互,它的优势在于更简洁、清晰、可读性强。

REST的主要特点是:

  1. 客户端和服务端是无状态的,任意请求都包含了处理需要的所有信息,同时服务端的变更对客户端是透明的。
  2. 资源用URI(Universal Resource Identifier 通用资源标识)来表示,通过请求方法来指明操作类型:GET/POST/PUT/DELETE。

无状态是最重要的特性,大部分的Client-Server,Brower-Server也都能很好的支持。第2点则是我们需要去关注的。

REST URL

表现层状态转移(REST)是一个大的概念,也不好理解,我的理解就是在URL的定义上能够清楚的表示其请求含义。它的核心思路就是动词+宾语:

DELETE www.baidu.com/api/v1/articles?author=1&category=2
# 动词 DELETE,表示要进行的操作是删除,即状态转移
# 宾语 articles,表示文章这种资源URI,推荐用复数,即表现层
# 定语 author=1&category=2,表示具体是什么资源
# 版本 api/v1,这个能够帮助我们更好的进行版本的升级,同时不影响原有的请求

我们用articles来指明资源类型,用author=1&category=2来在确定具体的资源,用GET/POST/PUT/DELETE来指明要进行的增删改查操作。

这种风格相比于/api/deleteArticles,声明的方法数量只有1/4,各个接口之间的风格也更加统一,调用起来更加清晰。

同时这种方法能够保证浏览器常规能访问的到的GET请求对资源来说是安全的。比如别人给我们发送了一个链接:/deleteArticle?id=1,我们绝对不会希望随便点击一下就会跳转到浏览器访问,然后误删了这个资源。


响应状态码

除了请求URL有要求,在响应时也有一些要求。我们知道状态码有:

  • 1xx: 请求相关信息
  • 2xx: 操作成功
  • 3xx: 重定向
  • 4xx: 客户端错误
  • 5xx: 服务端错误

所有的状态码 共有100多种,涵盖了绝大多数常见的网络场景,而且是网络通用的定义规范和解释,因此我们应该尽可能使用精确的状态码。

当前有一些不太恰当的做法是即便请求出错,依然使用200状态码,转而将错误信息包含在响应体中,或者响应使用纯文本导致无法和正常数据一样标准化解析,如:

httpCode: 200
response: {
    status: 1,
    msg: '请求无权限'
}
# 或:
httpCode: 200
response: '请求无权限'

但我们其实可以用更精确的状态码403代表权限不足,所以合适的响应结果应该是:

# 异常时
httpCode: 403,
httpErrorMsg: '请求无权限'
# 正常时:
httpCode: 200,
response: {
    status: 0,
    msg: '',
    data: []
}


总结

RESTful是一种API设计风格,并不是一种强制规范和标准,它的特点在于请求和响应都简洁清晰,可读性强。

我们主要关注几点:

  1. 无状态
  2. 请求URL = 动作(GET/POST/PUT/DELETE)+ 资源
  3. 响应使用精确的状态码和JSON格式数据


吐血推荐

1.站长广告联盟: 整理了目前主流的广告联盟平台,如果你有流量,可以作为参考选择适合你的平台点击进入...

2.休闲娱乐: 直播/交友    优惠券领取   网页游戏   H5游戏

链接: http://www.fly63.com/article/detial/4252

HTML5常用API

该API可以用来检测页面对于用户的可见性,即返回用户当前浏览的页面或标签tap的状态变化。 在最小化浏览器、切换tap页面时生效.(如需对app中几个webview进行切换操作时

API接口设计,需要注意这4点

原则上API接口设计一般出现在开发的详细设计中,但是随着诸多公司建立开放平台,产品经理也逐渐需要能理解API接口,尤其是做平台性的产品,还要学会定义接口。本文就关于产品经理在设计接口中需要定义什么

vue之按钮权限及优雅请求API

系统开发中按钮级权限控制也是非常重要的功能之一,可以严格控制不同角色用户所拥有的功能权限。首先可以通过vue的自定义指令来控制按钮(div,link也阔以)等的显示与否以及是否禁用状态。

webService和Restful

restful是一种架构风格,其核心是面向资源,更简单;而webService底层SOAP协议,主要核心是面向活动;两个都是通过web请求调用接口

使用 JS 来动态操作 css ,你知道几种方法?

JavaScript 可以说是交互之王,它作为脚本语言加上许多 Web Api 进一步扩展了它的特性集,更加丰富界面交互的可操作性。这类 API 的例子包括WebGL API、Canvas API、DOM API,还有一组不太为人所知的 CSS API

在 Node.js 上运行 Flutter Web 应用和 API

大量的跨平台应用开发框架,使你可以编写一次代码,然后在 Android,iOS 等多个平台上甚至在台式机上运行。你可能听说过一些流行的框架,例如 Ionic,Xamarin 和 React Native。另一个相对较新的框架是 Flutter

vue-next 函数式 api

在分享 vue-next 各个子模块的实现之前,我觉的有必要比较全面的整理下 vue-next 中提出的函数式 api,了解这些的话,无论是对于源码的阅读,还是当正式版发布时开始学习,应该都会有起到一定的辅助作用

解锁设计优质API的五种秘籍

如今,随着我们构建软件方式的变化,以及API平台的爆炸式激增,各大公司都必须以更快的速度构建出自己的产品、并推向市场。目前,几乎所有的软件需求都需要通过API来提供相应的解决方案,其中包括:支付类API、通信类API

Moment.js常用API速查

日常开发经常会用Moment.js来处理时间,现对频繁使用的几个API做下整理,以便日后查阅。

SDK 与API之间的关系和联系

SDK(Software Development Kit,软件开发工具包)一般都是一些软件工程师为特定的软件包、软件框架、硬件平台、操作系统等建立应用软件时的开发工具的集合,比如提供安卓开发工具、或者基于硬件开发的服务等。也有针对某项软件功能的SDK

fly63.com版权所有,内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权,请与小编联系!情况属实本人将予以删除!

文章投稿关于web前端网站点搜索站长推荐网站地图站长QQ:522607023

小程序专栏: 土味情话心理测试脑筋急转弯幽默笑话段子句子语录成语大全