Restful风格接口浅析

时间 2019-11-29

标签 restful 风格接口浅析繁體版

原文原文链接

为何使用RESTful
1．JSP技术可让咱们在页面中嵌入Java代码，可是这样的技术实际上限制了咱们的开发效率，由于须要咱们Java工程师将html转换为jsp页面，并写一些脚本代码，或者前端代码。这样会严重限制咱们的开发效率，也不能让咱们的java工程师专一于业务功能的开发，因此目前愈来愈多的互联网公司开始实行先后端分离。
2．近年随着移动互联网的发展，各类类型的Client层出不穷，RESTful能够经过一套统一的接口为Web，iOS和Android提供服务。另外对于广大平台来讲，好比微博开放平台，微信开放平台等，它们不须要有显式的前端，只须要一套提供服务的接口，RESTful无疑是最好的选择。RESTful架构以下： html

5、如何设计Restful风格的API
1.路径设计
—>在RESTful架构中，每一个网址表明一种资源（resource），因此网址中不能有动词，只能有名词，并且所用的名词每每与数据库的表名对应，通常来讲，数据库中的表都是同种记录的”集合”（collection），因此API中的名词也应该使用复数。
—>举例来讲，有一个API提供动物园（zoo）的信息，还包括各类动物和雇员的信息，则它的路径应该设计成下面这样。前端

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

java

1 你一直在错误的使用http协议web

如今微服务真是火的一塌糊涂！大街小巷，逢人必谈微服务，各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务！而做为微服务之间通讯的桥梁，Web API的设计就显得很是重要。数据库

Http是目前互联网使用最多的协议，没有之一！可是做为Http协议创始人之一的Roy Fielding认为，过去十年，你们都在错误的使用Http协议。删除一个数据，路径每每是 delete/{id} , 更新一条数据，路径每每被定义为update/{id}。你已经被Roy在内心默默的鄙视了！后端

Roy Fielding提出了一种用于设计Web服务的架构方法，称为Representational State Transfer（REST）。REST的概念是将API结构分离为操做和资源。使用HTTP方法GET、DELETE、POST和PUT操做资源。api

设计糟糕的REST API = 浪费时间！缓存

优秀的API就像一位艺术家在舞台上表演，其用户就是观众，能给全部人带来赏心悦目的美感！服务器

2 REST API里面的术语微信

Resource（资源）是指表明某种东西的对象，它具备一些与之相关的数据，而且能够有一组方法对其进行操做。例如。学校，班级和学生是资源，删除，添加，更新是要对这些资源执行的操做。

Collections（集合）是一组资源，例如，211大学是全国211所优质大学的集合。

URL（统一资源定位符）是能够经过其定位资源的路径，而且能够对其执行某些操做。

3 API设计使用名词，而不是动词

例如获取全部学生，可能经过以下api:

/getAllStudents,

增长学生，多是：/addNewStudent

更新学生，多是：/updateStudent

删除学生，多是：/deleteStudent

删除全部学生，多是：/deleteStudents

获取三好学生，多是：/getSanHaoStudents

更多操做......等等。

对于不一样的操做，会衍生出愈来愈多的API接口，数量不停的增多，接口将会变得混乱和难以维护。

有没有感受哪里不对？

URL应仅包含资源（名词）而不包含动做或者动词！增长学生的API路径：/addNewStudent，包含操做addNew以及资源名称Student。

正确的方法是什么？

/schools ，是一个很好的例子，不包含任何动做。可是咱们怎么告诉服务器，有关学校资源的操做呢，例如增长，删除或者更新学校？

这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)扮角色的地方！API接口的资源应始终为复数，若是咱们要访问资源的一个实例，咱们能够在URL中传递id或者name之类的。

GET 路径 /schools 获取全部的学校

GET 路径 /schools/清华获取名字叫清华大学的详细信息

DELETE 路径 /schools/清华从学校列表中，删除清华大学

资源和资源之间可能有父子关系，那又应该如何设计呢？例如学校的学生，下面是一些示例：

GET /schools/清华/students 获取清华大学的全部学生

GET /schools/清华/students/张三获取清华大学名字叫张三的学生的详细信息

DELETE /schools/清华/students/张三删除清华大学名字叫张三的学生

4 合理利用Http自己的方法

HTTP已定义了几组方法，这些方法指示要对资源执行什么类型的操做。咱们制定web接口，要合理利用http的方法！

URL是说白了，就是一个句子，其中资源是名词，HTTP方法是动词。

GET 方法从资源请求数据，不该产生任何其余做用。

例如/schools/清华/students，返回全部清华大学的学生

POST方法请求服务器在数据库中建立资源，主要是在提交Web表单时。

/schools/清华/students/张三，在清华大学的学生资源，新增一个张三的学生。

POST是非幂等的，这意味着多个请求将具备不一样的效果。

PUT方法请求服务器更新资源或建立资源（若是不存在）。

/schools/清华/students/张三，对清华大学下的学生资源中，更新或者建立张三。

PUT是幂等的，这意味着多个请求将具备相同的效果。

DELETE方法请求从数据库中删除资源或其实例。

/schools/清华/students/张三，从清华大学的学生集合中，删除学生张三的资源。

5 使用JSON做为通讯格式

JSON阅读性更高，扩展性更强，适合各类环境和语言进行解析，如今大的互联网公司，对外提供的API基本都使用JSON。

6 使用HTTP状态码

当客户端经过API向服务器发出请求时，客户端应该知道反馈，不管是失败，成功仍是请求错误。 HTTP状态代码是一系列标准化代码，针对http请求的可能会发生的各类状况。服务器应始终返回正确的状态代码。

不少人喜欢把错误信息放在返回值中，典型的Code和Message，其实比较Low。

下面是Http状态码，能够合理利用处理各类请求反馈，将http自身的错误和服务器内部的错误，有一个很好的区分。

2xx(成功类别)

200 Ok表示GET，PUT或POST成功的标准HTTP响应。

201 Created每当建立新实例时，都应返回此状态代码。例如，使用POST方法建立新实例时，应始返回201状态代码。

204 No Content表示请求已成功处理，但未返回任何内容。

3xx（重定向类别）

304 Not Modified表示客户端已在其缓存中有响应。所以无需再次传输相同的数据。

4xx（客户端错误类别）

这些状态代码表示客户端已提出错误请求。

400 Bad Request表示未处理客户端的请求，由于服务器没法理解客户端要求的内容。

401 Unauthorized表示不容许客户端访问资源，并应使用所需凭据从新请求。

403 Forbidden表示请求有效且客户端已经过身份验证，但不容许客户端出于任何缘由访问该页面或资源。例如，有时不容许受权客户端访问服务器上的目录。

404 Not Found表示请求的资源如今不可用。

410 Gone表示已移动的请求资源再也不可用。

5xx（服务器错误类别）

500内部服务器错误表示请求有效，但服务器彻底混淆，并要求服务器提供某些意外状况。

503 Service Unavailable表示服务器已关闭或没法接收和处理请求。大多数状况下，例如服务器正在进行维护。

7 搜索，排序，过滤和分页

全部这些操做都只是对一个数据集的查询。将不会有新的API集来处理这些操做。咱们须要使用GET方法API附加查询参数。

下面看几个例子：

GET /schools ? search = 清华大学在大学集合中，搜索清华大学

GET /schools ? sort = rank_asc 按照升序排列学校

GET /schools ? location = 北京按照城市对学校过滤

GET /schools ? page=6 获取第六页的学校列表

8 使用版本控制

例以下面两个版本地址：

http://api.yourservice.com/v1/schools/清华

http://api.yourservice.com/v2/schools/清华

在API上加入版本信息能够有效的使用户访问正确的API，v2是新开发功能，开发阶段，让全部用户访问v1，等开发完成统一切到v2。

能够有效的跨版本访问，例如在v2版本，还须要访问v1版本的一些接口

9 总结

1，API接口都用小写

2，使用JSON通讯

3，API带版本控制，好比v1,v2

4，使用Token令牌进行鉴权

5，路径中单词链接使用中划线-

6，使用HTTP自身的方法表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除

7，合理使用HTTP状态码，200，201，400，401，403，500。好比401表示用户身份认证失败，403表示你验证身份经过了，可是无权限操做资源。