Restful API解释及工作中的实践

写在前面

在工作中，我使用的后台框架是完全遵循Restful API设计的。

遂系统的梳理一遍RESTful API的概念，并且加以工作中的实例，巩固自己的知识，也便于读者更好的理解RESTful API。

什么是RESTful API？

我们可以分为两块来理解，RESTful API = RESTful + API, 也就是基于RESTful的API，那么问题就变成了，什么是RESTful？

先一言以概之：RESTful是网络接口设计应当遵循的一套规范，这套规范包括了一组架构约束条件和原则。

REST全称是Representational State Transfer，中文意思是表述性状态转移。通常市面上所说的RESTful API，都是指其风格在HTTP上的应用，但这只是因为目前HTTP是唯一与REST相关的实例。

RESTful最重要的特征，就是面向资源，通俗一点说，url中只能有名词，动词对应的行为由http方法决定。当然，RESTful还有其他的东西，这个我们之后再看。

举个例子？

最近新开发的网页应用，需求是A公司邀请B公司建立合作关系。具体到实现，就是A公司要能够发送邀请，B公司要能够接受邀请。因为这篇文章只讨论API，所以前端实现全部略过。

假设我已经搭建好了服务器：https://server-address 那么下一步，就是后台实现方法并且暴露给前端调用。

那我们先实现一个A公司发送邀请的功能吧，未经思考，我们给出答案：https://server-address/createInvitation( id = '001')

这个uri的意思是，调用createInvitation对应的后台资源，创建一条id='001'的invitation。

燃鹅，如果我们这样设计，那么我们一下就违背了两条RESTful的规范：

先说违背了哪两条：

1. 前面说过，要面向资源，也就是用名词取名。

2. 要用标准的HTTP方法与后台实现对应，createInvitation(id = '001')实际上用的是get方法来传参数，而get方法应该是幂等的，只用来读取资源，标准的方法应该是调用post方法，把id='001'放进HTTP request 的header中去。

我们给资源的取名是：createInvitation，实际上的主体是动词，可能有同学要说了，我这个是动名词短语做名词呀。那你太秀了，请陈独秀同学坐下来发言。

不如我们先想想，遵循RESTful的话，应该如何设计创建邀请？ 答案是： https://server-address/invitations, 注意我用的是复数形式，不要单复数混用，容易引起麻烦

答案我知道了，那这样有什么好处呢？ 对于invitation这个资源来说，现在只有创建的需求，但是当A公司需要取消，修改时，如果我们用的是createInvitation作为创建的uri，难以避免要新建deleteInvitation，updateInvitation这两个新的uri，而如果采用invitation作为uri，在新建的时候前端用post方法调用https://server-address/invitations, 在取消（删除）invitation时，用delete方法调用，在修改invitation时，用put方法调用。也就是说，所有对invitation的操作，调用的都是https://server-address/invitations这个url，是不是很符合逻辑，也很简洁明了呢？

我认为RESTful最关键的思维就是上述这个例子了，这是每一个API应该遵守的最佳实践。

更多：

RESTful还有其他的比如关于API的版本等等更详细的规范，这些都是按需使用的，具体可以参考：

RESTful架构详解：http://www.runoob.com/w3cnote/restful-architecture.html

RESTful API的十个最佳实践：https://www.cnblogs.com/xiaoyaojian/p/4612503.html

如果对HTTP方法不熟，可以参考：

http几种请求方法的差别：https://blog.csdn.net/resilient/article/details/52585724