RESTful API 设计指南 (转)

RESTful API 设计指南

2016-02-23 ImportNew

(点击上方公号，可快速关注)

 

作者：阮一峰

链接：http://www.ruanyifeng.com/blog/2014/05/restful_api.html

 

网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备……）。

 

因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现”API First”的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。我以前写过一篇《理解RESTful架构》，探讨如何理解这个概念。

 

今天，我将介绍RESTful API的设计细节，探讨如何设计一套合理、好用的API。我的主要参考了两篇文章（1，2）。

 

一、协议

 

API与用户的通信协议，总是使用HTTPs协议。

 

二、域名

 

应该尽量将API部署在专用域名之下。

 

https://api.example.com

 

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

 

https://example.org/api/

 

三、版本（Versioning）

 

应该将API的版本号放入URL。

 

https://api.example.com/v1/

 

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

 

四、路径（Endpoint）

 

路径又称”终点”（endpoint），表示API的具体网址。

 

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

 

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

 

https://api.example.com/v1/zoos

 

https://api.example.com/v1/animals

 

 

https://api.example.com/v1/employees

 

五、HTTP动词

 

对于资源的具体操作类型，由HTTP动词表示。

 

常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

 

  • GET（SELECT）：从服务器取出资源（一项或多项）。

  • POST（CREATE）：在服务器新建一个资源。

  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

  • DELETE（DELETE）：从服务器删除资源。

 

还有两个不常用的HTTP动词。

 

  • HEAD：获取资源的元数据。

  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

 

下面是一些例子。

 

  • GET /zoos：列出所有动物园

  • POST /zoos：新建一个动物园

  • GET /zoos/ID：获取某个指定动物园的信息

  • PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）

  • PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）

  • DELETE /zoos/ID：删除某个动物园

  • GET /zoos/ID/animals：列出某个指定动物园的所有动物

  • DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

 

六、过滤信息（Filtering）

 

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

 

下面是一些常见的参数。

 

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

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

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

  • ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

  • ?animal_type_id=1：指定筛选条件

 

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

 

七、状态码（Status Codes）

 

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

 

  • 200 OK – [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

  • 201 CREATED – [POST/PUT/PATCH]：用户新建或修改数据成功。

  • 202 Accepted – [*]：表示一个请求已经进入后台排队（异步任务）

  • 204 NO CONTENT – [DELETE]：用户删除数据成功。

  • 400 INVALID REQUEST – [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

  • 401 Unauthorized – [*]：表示用户没有权限（令牌、用户名、密码错误）。

  • 403 Forbidden – [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。

  • 404 NOT FOUND – [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

  • 406 Not Acceptable – [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。

  • 422 Unprocesable entity – [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

  • 500 INTERNAL SERVER ERROR – [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

 

状态码的完全列表参见这里。

 

八、错误处理（Error handling）

 

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

 

{ error: "Invalid API key" }

 

九、返回结果

 

针对不同操作，服务器向用户返回的结果应该符合以下规范。

 

  • GET /collection：返回资源对象的列表（数组）

  • GET /collection/resource：返回单个资源对象

  • POST /collection：返回新生成的资源对象

  • PUT /collection/resource：返回完整的资源对象

  • PATCH /collection/resource：返回完整的资源对象

  • DELETE /collection/resource：返回一个空文档

 

十、Hypermedia API

 

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

 

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

 

{"link": { "rel": "collection https://www.example.com/zoos", "href": "https://api.example.com/zoos", "title": "List of zoos", "type": "application/vnd.yourformat+json" }}

 

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

 

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

 

{ "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations", // ... }

 

从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。

 

{ "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

 

上面代码表示，服务器给出了提示信息，以及文档的网址。

 

十一、其他

 

（1）API的身份认证应该使用OAuth 2.0框架。

 

（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。

 

【今日微信公号推荐↓】

更多推荐请看《值得关注的技术和设计公众号》

 

其中推荐了包括技术、设计、极客和IT相亲相关的热门公众号。技术涵盖：Python、Web前端、Java、安卓、iOS、PHP、C/C++、.NET、Linux、数据库、运维、大数据、算法、IT职场等。点击《值得关注的技术和设计公众号》，发现精彩！

 

转自：链接

转载于:https://www.cnblogs.com/YangBinChina/p/5220284.html

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/404264.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

find：查找文件或目录

find：查找文件或目录

From: http://yhj1065.blog.163.com/blog/static/198002172007111810502948/ 功能说明： find指令可以在系统中查找你想要的任何文件或目录，你可以通过不同的参数来查找你想要的。该指令也是系统管理员最常用、最强大、最方便的查找文件和目录的指令。 基…
阅读更多...
[Redux/Mobx] 为什么redux能做到局部渲染呢？

[Redux/Mobx] 为什么redux能做到局部渲染呢？

[Redux/Mobx] 为什么redux能做到局部渲染呢？ reducer从根往最子级的reducer中间各层总是返回一个新的state，这样的话，就会引起组件的大范围的re-render，但是这是可避免的 合理的利用selector：在connect函数中的第一个…
阅读更多...
[zz]Linux操作系统下三种配置环境变量的方法

[zz]Linux操作系统下三种配置环境变量的方法

个人的总结: 设置了/etc/profile 和 ~/.bashrc 之后，使用了source 命令，是可以echo添加的变量，但是用getenv读不出来，然后使用env命令也显示不出来，是因为没有export!! ---------------------------------------------…
阅读更多...
poj 2976 基础01分数规划

poj 2976 基础01分数规划

这个题算是01分数规划的最基本的应用了， 01分数规划是给你n对数(a1, b1)....(an, bn), 然后让你选择一些数对， 使得sigma(ai)/sigma(bi)最大。这里附上讲解一份， http://blog.csdn.net/hhaile/article/details/8883652， 代码如下&…
阅读更多...
删除(.svn)目录

删除(.svn)目录

windows 平台： Windows Registry Editor Version 5.00[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Folder\shell\DeleteSVN] "Delete SVN Folders"[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Folder\shell\DeleteSVN\command] "cmd.exe /c \"TITLE Remov…
阅读更多...
[Redux/Mobx] 举例说明怎么在redux中定义action？

[Redux/Mobx] 举例说明怎么在redux中定义action？

[Redux/Mobx] 举例说明怎么在redux中定义action？ 利用actionCreator // 用户选择需要显示的subredditexport const SELECT_SUBREDDIT SELECT_SUBREDDITexport function selectSubreddit(subreddit) {return {type: SELECT_SUBREDDIT,subreddit} } 个人简介 我是…
阅读更多...
模式——工程化实现及扩展（设计模式Java 版）

模式——工程化实现及扩展（设计模式Java 版）

--模式——工程化实现及扩展（设计模式Java 版）王翔，孙逊著ISBN 978-7-121-15638-02012年4月出版定价：59.00元16开416页内 容 简 介设计模式不是一门适合空谈的技术，它来自于开发人员的工程实践又服务于工程实践。本书并…
阅读更多...
异构计算

异构计算

异构计算的英文名称是Heterogeneouscomputing，主要是指使用不同类型指令集和体系架构的计算单元组成系统的计算方式。常见的计算单元类别包括CPU、GPU等协处理器、DSP、ASIC、FPGA等。 有点看不懂，没关系，有位大神给了一个通俗的解释&#xf…
阅读更多...
[Redux/Mobx] Redux怎样设置初始状态？

[Redux/Mobx] Redux怎样设置初始状态？

[Redux/Mobx] Redux怎样设置初始状态？ redux包里面的createStore方法的第二个可选参数即可设置state的初始值在定义从根到子的reducer时，可以通过默认参数的方式定义state的初始值 个人简介 我是歌谣，欢迎和大家一起交流前后端知识。放弃很…
阅读更多...
由Qt中qApp想到的(这是单例模式么？？？)

由Qt中qApp想到的(这是单例模式么？？？)

From: http://blog.csdn.net/qq575787460/article/details/7880972 学Qt时，发现只要包含头文件QApplication或者QCoreapplication，就用使用qApp，指向一个当前实例。 查看源码发现qApp是个宏： QApplication中：#define q…
阅读更多...
根据网页地址获取页面内容

根据网页地址获取页面内容

public JSONObject urlConn(String urlStr, String portStr){ String port getPort(portStr); urlStr (urlStr ! null)?(host port "/?" urlStr):(host port); int responseCode; try { url new URL(urlStr); conn (HttpURLConnection) url.openConnection…
阅读更多...
bootstrap基础学习十篇

bootstrap基础学习十篇

bootstrap字体图标（Glyphicons） a.什么是字体图标 字体图标是在 Web 项目中使用的图标字体。虽然，Glyphicons Halflings 需要商业许可，但是您可以通过基于项目的 Bootstrap 来免费使用这些图标。 b.bootstrap自带字体图标文件结构…
阅读更多...
Python 用hashlib求中文字符串的MD5值

Python 用hashlib求中文字符串的MD5值

From： http://blog.csdn.net/haungrui/article/details/6959340 使用过hashlib库的朋友想必都遇到过以下的错误吧：“Unicode-objects must be encoded before hashing”，意思是在进行md5哈希运算前，需要对数据进行编码。而且在不…
阅读更多...
[Redux/Mobx] Mobx的设计思想是什么

[Redux/Mobx] Mobx的设计思想是什么

[Redux/Mobx] Mobx的设计思想是什么 依赖收集。在Mobx中，定义了observable的属性，mobx会自动跟踪这个属性值的变化；在用了mobx与react的桥接库mobx-react之后，这种跟踪关系会体现了视图上，JSX依赖的observable属性值变…
阅读更多...
csu 1008 - Horcrux

csu 1008 - Horcrux

不得不表示，能用栈来做的题目前对我来说都很费解，这题又是抄的，来自校友JMDWQ，只不过把C改成了C。开始时我用的是暴搜，数组的每一位就是一个“魂器”，而他的栈结构里每一位是连续相同的“魂器”的长度&…
阅读更多...
0301——SearchController

0301——SearchController

创建显示的页面 SearchViewController * searchVC [[SearchViewController alloc]init]; 告诉搜索控制器将结果显示在创建的页面上 self.searchController [[UISearchController alloc]initWithSearchResultsController:searchVC]; 由谁来监听搜索内容发生的事件 self.search…
阅读更多...
[Redux/Mobx] 推荐在reducer中触发Action吗？为什么？

[Redux/Mobx] 推荐在reducer中触发Action吗？为什么？

[Redux/Mobx] 推荐在reducer中触发Action吗？为什么？ 不推荐。首先reducer应该是一个纯函数，reducer中的代码应该把代码逻辑限定在当前的reducer内，如果触发了action，会触发其它的reducer、甚至再次触发自身&#xff0…
阅读更多...
windows等宽字体

windows等宽字体

From: http://plplum.blog.163.com/blog/static/310324002009814105634/ windows下的等宽字体： BatangChe Courier Courier New DotumChe Fixedsys GulimChe GungsuhChe Lucida Console Lucida Sans Typewriter MingLiU MS Gothic MS Mincho Terminal 仿宋_GB2312 楷…
阅读更多...
JS中的Replace方法

JS中的Replace方法

最近查一个bug，原因是JS中的Replace方法造成的，当将一个字符串中有处需要替换时，一般会用到JS中的Replace方法，Replace方法的第一个参数如果是传的字符串，只会替换第一处。代码如下： var str "0CEA65…
阅读更多...
sed替换变量

sed替换变量

今天在写脚本时用到了sed，我用sed替换xml文件中的变量。一般在sed 中替换都用单引号，如下边 sed -i ‘s/10/1000/g’ test.xml但是如果需要把1000改成变量，如sed -i ’s/10/$num/g‘ test.xml这样就不成功。 此时需要把单引号改成双引号,如下…
阅读更多...
最新文章

Copyright @ 2022~2023