RESTful API 最佳实践

转载自  RESTful API 最佳实践

RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。

它的大原则容易把握,但是细节不容易做对。本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API。

 

一、URL 设计

1.1 动词 + 宾语

RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles这个命令,GET是动词,/articles是宾语。

动词通常就是五种 HTTP 方法,对应 CRUD 操作。

  • GET:读取(Read)
  • POST:新建(Create)
  • PUT:更新(Update)
  • PATCH:更新(Update),通常是部分更新
  • DELETE:删除(Delete)

根据 HTTP 规范,动词一律大写。

1.2 动词的覆盖

有些客户端只能使用GETPOST这两种方法。服务器必须接受POST模拟其他三个方法(PUTPATCHDELETE)。

这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。


POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

上面代码中,X-HTTP-Method-Override指定本次请求的方法是PUT,而不是POST

1.3 宾语必须是名词

宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

  • /getAllCars
  • /createNewCar
  • /deleteAllRedCars

1.4 复数 URL

既然 URL 是名词,那么应该使用复数,还是单数?

这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。

为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2

1.5 避免多级 URL

常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。


GET /authors/12/categories/2

这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。

更好的做法是,除了第一级,其他级别都用查询字符串表达。


GET /authors/12?categories=2

下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。


GET /articles/published

查询字符串的写法明显更好。


GET /articles?published=true

二、状态码

2.1 状态码必须精确

客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数,分成五个类别。

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

这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。

API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。

2.2 2xx 状态码

200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

  • GET: 200 OK
  • POST: 201 Created
  • PUT: 200 OK
  • PATCH: 200 OK
  • DELETE: 204 No Content

上面代码中,POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。

此外,202 Accepted状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。下面是一个例子。


HTTP/1.1 202 Accepted{"task": {"href": "/api/company/job-management/jobs/2130040","id": "2130040"}
}

2.3 3xx 状态码

API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。

API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。它与302307的含义一样,也是"暂时重定向",区别在于302307用于GET请求,而303用于POSTPUTDELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。下面是一个例子。


HTTP/1.1 303 See Other
Location: /api/orders/12345

2.4 4xx 状态码

4xx状态码表示客户端错误,主要有下面几种。

400 Bad Request:服务器不理解客户端的请求,未做任何处理。

401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。

403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。

404 Not Found:所请求的资源不存在,或不可用。

405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。

410 Gone:所请求的资源已从这个地址转移,不再可用。

415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。

422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。

429 Too Many Requests:客户端的请求次数超过限额。

2.5 5xx 状态码

5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。

503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

三、服务器回应

3.1 不要返回纯本文

API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json

客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。


GET /orders/2 HTTP/1.1 
Accept: application/json

3.2 发生错误时,不要返回 200 状态码

有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。


HTTP/1.1 200 OK
Content-Type: application/json{"status": "failure","data": {"error": "Expected at least two items in list."}
}

上面代码中,解析数据体以后,才能得知操作失败。

这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。


HTTP/1.1 400 Bad Request
Content-Type: application/json{"error": "Invalid payoad.","detail": {"surname": "This field is required."}
}

3.3 提供链接

API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。

举例来说,GitHub 的 API 都在 api.github.com 这个域名。访问它,就可以得到其他 URL。


{..."feeds_url": "https://api.github.com/feeds","followers_url": "https://api.github.com/user/followers","following_url": "https://api.github.com/user/following{/target}","gists_url": "https://api.github.com/gists{/gist_id}","hub_url": "https://api.github.com/hub",...
}

上面的回应中,挑一个 URL 访问,又可以得到别的 URL。对于用户来说,不需要记住 URL 设计,只要从 api.github.com 一步步查找就可以了。

HATEOAS 的格式没有统一规定,上面例子中,GitHub 将它们与其他属性放在一起。更好的做法应该是,将相关链接与其他属性分开。


HTTP/1.1 200 OK
Content-Type: application/json{"status": "In progress","links": {[{ "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,{ "rel":"edit", "method": "put", "href":"/api/status/12345" }]}
}

四、参考链接

  • RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca
  • API design, by MicroSoft Azure

(完)

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

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

相关文章

selenium以及chromdrive安装

selenium的安装比较简单,直接pip install selenium就可以了 看有些网上写的chromedrive安装好麻烦啊,我win10自己试了下,感觉并不需要配置那么多环境变量。 直接性 http://npm.taobao.org/mirrors/chromedriver/ 找到相应的chrome版本即可 至…

将两个递增的有序链表合并为一个递增的有序链表。要求结果链表仍使用原来两个链表的存储空间,不另外占用其他的空间。表中不允许又重复的数据

#include<iostream> using namespace std;typedef struct lnode {//定义结点类型int data;struct lnode *next;//递归定义 } lnode,*LinkList;void CreateList(LinkList &L,int n) {//创建新链表Lnew lnode;//生成一个头结点L->nextNULL;//结点L的next置空for(int…

ssl提高组周二备考赛【2018.10.30】

前言 依旧想去德育基地… 成绩 RankRankRankPersonPersonPersonScoreScoreScoreAAABBBCCC1112017xxy2017xxy2017xxy2102102104040401001001007070702222017myself2017myself2017myself1901901902020201001001007070703332017lxf2017lxf2017lxf1801801800009090909090904442017…

通过C#/.NET API使用CNTK

CNTK v2.2.0提供C#API来建立、训练和评估CNTK模型。 本节概要介绍了CNTK C#API。 在CNTK github respository中可以找到C#训练示例。 使用C&#xff03;/ .NET管理API构建深层神经网络 CNTK C#API 通过CNTKLib命名空间提供基本操作。 CNTK操作需要一个或两个具有必要参数的输入…

Kafka Controller Redesign 方案

转载自 Kafka Controller Redesign 方案 Kafka Controller 是 Kafka 的核心组件&#xff0c;在前面的文章中&#xff0c;已经详细讲述过 Controller 部分的内容。在过去的几年根据大家在生产环境中应用的反馈&#xff0c;Controller 也积累了一些比较大的问题&#xff0c;而针…

做个人网站的原因

昨天b站上看视频&#xff0c;浏览评论时&#xff0c;看到一个网址 https://xiaoyou66.com/ 博主写了大概一百篇的文章&#xff0c;我进来的时候真的是被这js特效给惊到了&#xff0c;个人网站也能变得这么二次元嘛&#xff0c;讲实话&#xff0c;光是看这酷炫的页面都比较有欲望…

nssl1257-A【数论】

正题 题目大意 对于n个数组成的序列&#xff0c;求排好序需要最少交换次数的期望次数。 解题思路 我们可以先求出需要次数总和在乘上n!n!n!的逆元 先打一个表&#xff0c;不难发现 f(n)f(n−1)∗n(n−1)(n−1)!f(n)f(n-1)*n(n-1)(n-1)!f(n)f(n−1)∗n(n−1)(n−1)! 然后我们在…

一文理解Netty模型架构

转载自 一文理解Netty模型架构 本文基于Netty4.1展开介绍相关理论模型&#xff0c;使用场景&#xff0c;基本组件、整体架构&#xff0c;知其然且知其所以然&#xff0c;希望给读者提供学习实践参考。 1 Netty简介 Netty是 一个异步事件驱动的网络应用程序框架&#xff0c;用…

尝试涉猎更多领域

昨天b站上看视频&#xff0c;浏览评论时&#xff0c;看到一个网址 https://xiaoyou66.com/ 博主写了大概一百篇的文章&#xff0c;我进来的时候真的是被这js特效给惊到了&#xff0c;个人网站也能变得这么二次元嘛&#xff0c;讲实话&#xff0c;光是看这酷炫的页面都比较有欲望…

nssl1258-naive的瓶子【贪心】

正题 题目大意 有n个瓶子&#xff0c;将一个瓶子变成相邻一个瓶子的颜色价值为它们颜色值的乘积&#xff0c;求将所有瓶子变成同一个颜色的最低价值。 解题思路 枚举最后的剩下的颜色&#xff0c;然后对于每个瓶子只有两种可能 1.直接变成那个颜色 2.变成别的颜色在变成那个颜…

聊聊分布式事务,再说说解决方案

前言 最近很久没有写博客了&#xff0c;一方面是因为公司事情最近比较忙&#xff0c;另外一方面是因为在进行 CAP 的下一阶段的开发工作&#xff0c;不过目前已经告一段落了。 接下来还是开始我们今天的话题&#xff0c;说说分布式事务&#xff0c;或者说是我眼中的分布式事务&…

已知两个链表A和B分别表示两个集合,其元素递增排列。请设计算法求出两个集合A和集合B的差集(近由在A中出现而不再B中出现的元素所构成的集合),并以同样的形式存储,同时返回该集合的元素个数。

#include <iostream> using namespace std; //第四题 typedef struct Lnode {int data;struct Lnode *next;} lnode, *linklist; void creatlist_h(linklist &L, int n) {lnode *p;Lnew lnode;L->nextNULL;for(int i0; i<n; i){pnew lnode;cin>>p->da…

Redis+Tomcat+Nginx集群实现Session共享,Tomcat Session共享

转载自 RedisTomcatNginx集群实现Session共享&#xff0c;Tomcat Session共享 一、Session共享使用tomcat-cluster-redis-session-manager插件实现 插件地址见&#xff1a; https://github.com/ran-jit/tomcat-cluster-redis-session-manager 该插件支持Tomcat7、Tomcat8、To…

个人博客搭建

先下载node.js 用npm或cnpm安装hexo cnpm install hexo 再创建一个文件夹&#xff0c;在文件夹目录下打开cmd 输入 hexo init 输入 hexo s 这就在本地算是完成了一个博客的创建 新建博客hexo n ‘Hello world’ hexo clean hexo s 就可以再次启动&#xff0c;这样 记得先 cn…

C#使用Xamarin开发可移植移动应用进阶篇(10.综合演练,来一份增删改查CRUD)

说点什么.. 呃 也有半个月没更新了. 本来这篇的Demo早就写完了,文章也构思好了.迟迟没发布..是因为实在太忙.. 项目要上线..各种 你们懂的.. 正赶上自己十一人生大事..结婚..所以..忙的那叫一个脚不沾地啊. 今天的学习内容? 使用我们前面所学的技术,写一个增删改查. 效果如下…

nssl1259-sequence【组合数,差分】

正题 题目大意 操作(l,r,k)(l,r,k)(l,r,k)表示 l∼rl\sim rl∼r这段区间&#xff0c;对于每个iii&#xff0c;加上Ckik−lC_k^{ik-l}Ckik−l​ 解题思路 我们可以发现对于一个全是1的序列&#xff0c;求kkk次前缀和&#xff0c;就是杨辉三角的第k1k1k1列&#xff0c;那么对于…

hexo部署在码云出现样式问题

然而本地服务器并没有任何问题 重建一个 重新建一个仓库 还是这种情况&#xff0c;回头再找原因&#xff0c;两次都是这种情况&#xff0c;就是配置错了 借用 https://blog.csdn.net/xiangwanpeng/article/details/53155642 https://blog.csdn.net/qq_29347295/article/deta…

当你输入一个网址的时候,实际会发生什么?

转载自 当你输入一个网址的时候&#xff0c;实际会发生什么? 译文:http://igoro.com/archive/what-really-happens-when-you-navigate-to-a-url/ 作为一个软件开发者&#xff0c;你一定会对网络应用如何工作有一个完整的层次化的认知&#xff0c;同样这里也包括这些应用所…

SIMD via C#

简介 TL;DR 我们为C#&#xff08;准确地说是.NET Core&#xff09;引入了一套全新的机制&#xff0c;使得C# 以后可以像C/C 一样直接使用intrinsic functions 来直接操作Intel CPU 的大多数SIMD 指令了&#xff08;从SSE 到AVX2&#xff09;。 &#xff08;注意是以后&#xff…

ssl提高组周三备考赛【2018.10.31】

前言 呆学校呆3天依旧不想复习期中&#xff0c;感觉要凉。 成绩 RankRankRankPersonPersonPersonScoreScoreScoreAAABBBCCC1112017myself2017myself2017myself1801801801001001008080800002222014yqf2014yqf2014yqf1401401400004040401001001004442017lw2017lw2017lw808080000…