restful

什么是API

API全称Aplication Programming Itererface即应用程序编程接口， 我们在开发应用程序时经常用到。API作为接口，用来“连接”两个不同的系统，并使其中一方为另一 方提供服务，比如在操作系统上运行的应用程序能够访问操作系统所提供的API,并通过这些API来调用操,作系统的各种功能。因此，API 是一个系统向外暴露或公开的一套接口， 通过这些接口，外部应用程序能够访问该系统。在Web应用程序中，Web API具有同样的特性，它作为一个Web应用程序，向外提供了,在Web应用程序中，Web API具有同样的特性，它作为一个Web应用程序，向外提供了一些接口， 这些接口的功能通常是对数据进行操作,一些接口， 这些接口的功能通常是对数据进行操作(如获取或修改数据等)，它们能够被外部应用程序，比如桌面应用程序、手机应用甚至其他Web应用程序(如ASP.NET Core MVC视图应用、单页Web应用)等访问并调用。WebAPI能够实现不同应用程序之间的访问，它与平台或编程语言无关，可以使用不同的技术来构建Web API,如Java、.NET等;

什么是REST

REST(Representational State Transfer) 表述性传递状态，Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格，作为一种web服务的设计与开发方式，Rest可以降低开发的复杂性，提高系统的可伸缩性。

REST是一种基于资源的架构风格，在REST中，资源(Resource)是最基本的概念任何能够命名的对象都是资源，如：user,team,order,docment。他表示web服务要操作的一个实体，一个资源具有一个统一资源标识符。(Uniform Resource Identifier URI),如 users/123。通过资源能够标识并访问资源。

资源标识

主键编号进行标识

资源集合

除了单个资源外，资源集合表示多个相同类型的资源，如users。在系统设计时，不同的实体之间往往存在着某种关联关系。如一个用户有多个订单。同样，在REST中，这种关联关系也能够有资源之间的层次关系体现出来。如users/123/orders/1

由于REST资源为中心，因此REST接口的端点(Endpoint)均以资源或资源集合结尾，它不像其他形式的WEB服务一样以动词结尾，如api/GetUserInfo或者api/UpdateUserInfo。在REST中，对资源的动作或操作是通过HTTP方法来完成的。如下

GET http://api . domain. com/users/1234 查询

PUThttp://api . domain. com/users/1234 修改

上例中用到了两个HTTP方法，分别为GET与PUT,它们的作用分别是获取和更新指定资源，当请求方发起请求，修改了资源的状态后，更新后的资源表述应返回给请求方，这也是表述性状态传递的意义。

同时我们可以知道，REST是和HTTP有一定的关系，资源在服务的提供方和请求方之间进行传递。需要借助于协议来约定，比如协议所规定的消息格式等，而HTTP协议则是非常成熟且广泛使用的网络协议。事实上，HTTP协议完全满足REST中所定义的约束。因此，REST可以轻松的使用HTTP协议及其中的功能(如TTP方法，HTTP消息等)，并设计出松耦合的Web服务

REST约束

客户端-服务端

​ 客户端-服务端约束体现了关注点分离原则，使客户端与服务端各自能够独立实现并独立开发，只要他们之间的接口不改变即可，客户端可以使用不同的技术或编程语言。

统一接口

​ 统一接口是设计任何RESTful服务的基础，也是区别Rest风格与其他web服务风格的最主要体现，系统中多个组件（服务器，客户端，以及可能存在的代理服务器等）都依赖统一接口，分别由4个子约束组成

​ 资源标识

​ users/123,orders/12,docment/12

​ 通过表述操作资源

​ 格式通常为json,xml，html等，最好是

​ json {user:{“id”:123,“name”:Tom}} xml 123Tom

​ 自描述信息

​ 客户端和服务端之前传递的每一条消息都应包含足够的信息，这些信息不仅包含了资源的表述，也包含了资源表述的相关信息（格式和内容长度），甚至包含了资源相关的其他操作信息。

​ 超媒体作为应用程序状态引擎(HATEOAS)

​ 服务器返回的资源表述中不仅要包含资源的表述，也应包含与之相关的链接，这些链接能够对资源执行其他操作。比如当获取资源时，返回的链接中，包含更新该资源，删除资源等链接

分层系统

​ 分层系统约束能够使用网络中介（如代理和网关）透明地部署到客户端和服务端之间，只能能够遵守并且使用前面提到的统一接口约束即可，客户端和服务端都不知道网络中介的存在。中间服务器主要用于增强安全，负载均衡和响应缓存等目的

缓存

缓存是web架构中重要的特性之一，客户端和网络中介均能够缓存服务器返回的响应，因此当服务器返回响应时，应指明该响应的缓存特性，对响应进行缓存将有助于减少数据获取延迟以及对服务器的请求，从而提高系统的性能。

无状态

​ 无状态约束将指明服务器不会记录或存储客户端的状态信息，反之，这些状态信息应有客户端来保存并维护，因此客户端对服务的请求不能依赖已发生的其他请求，当客户端请求服务器时，必须在请求消息中包含所有与之相关的信息（如认证信息等）

按需编码

按需编码约束允许服务器临时向客户端返回可执行的程序代码（如脚本等），返回这些代码用户为客户端提供扩展或自定义的功能，由于客户端必须理解并能够执行服务器返回的代码，因此这一约束增加了客户端和服务器之间的耦合，同时，这一约束是可选的 。

Restful api设计

对于REST及其约束，将有助于我们设计RESTful服务或Restful API,

在关注点方面 RESTful api 主要是面向资源，RPC 面向功能

在api断点方面，REST 的端点是名词，是资源或资源集合，而RPC的端点是动词、是方法名

在执行特点方面，REST对资源执行操作，RPC执行服务器上的方法

在返回结果方面，REST返回请求的资源，而RPC则返回调用方法的执行结果

什么是HTTP协议

超文本传输协议

1、URL 统一资源定义符

2、媒体类型

​ 也就是说的内容类型，Content Type

3、http消息

​ 也就是http之间交互的语言

​ 3.1 起至行

​ 3.2 HTTP消息头

​ 对于消息体的描述，和一些相关的配置

​ 3.3 空行

​ 3.4 HTTP消息体（资源，html表单）

4、http方法

​ GET POST PUT DELETE PATCH HEAD OPTIONS

​ GET 获取资源

​ POST 创建资源

​ PUT 修改资源

​ DELETE 删除资源

​ PATCH 资源部分更新 与 PUT 类似，但是是部分更新

​ HEAD 不会放回消息正文，和 GET类似

​ OPTIONS 方法用户获取资源支持的操作，

5、http消息头

​ http请求头

​ http响应头

6、状态码

​ 1XX : 信息

​ 2XX : 成功

​ 3XX ：重定向

​ 4XX：客户端错误

​ 5XX：服务端错误

rest最佳实践

原则：

1、使用名词对的复数表示一个资源集合，如api.domain.com/users

2、使用斜线“/”用来表示资源之间的层次关系，如api.domain.com/users/1234/orders

3、对资源的增，删，改，查等操作名称不应包含在URL中，反之应正确使用HTTP方法，比如，GET/deleteuser/1234(错误)，DELETE users/1234(正确)

4、如果一个操作无法对应到资源的某个操作上，此时可以适当地在URI中包含动词，但依然应该基于一个资源的标识符。例如：

PUT /users/1234/set-admin

DELETE /users/1234/set-admin

5、查询字符串可以用来对资源进行筛选、搜索或分页查询等操作，如下所示

GET /users?role=admin

GET /users?searchQuery=abc

GET /users?pageSize=25&pageNumber=2

6、URI 中应尽量使用小写字母

7、URI中可以使用中划线“-”来增加其可读性，如使用“-”来代替空格

​ http://api.domain.com/blogs/this-is-my-first-post

8、URI中不应使用下划线

​ URI中通常会带有下划线，以表示它是可点击的，这个下划线将会使URI中下划线不可见，可以使用“-”代替

9、URL末尾不应包含斜线“/”

​ 例如：/users/1234/ 错误 /users/1234 正确

restful API资源标识格式

​ JSON和XML为常用到的两种资源表述格式，他们都可以用来传递数据，且都有简洁，自描述的特点

restful api 版本

当api 发生了变化，比如资源表述内容有新增字段(字段或属性)或系统添加了新资源类型时，应使用不同的版本来区别对API的更改，为 restful api 添加版本有以下4方式

1、使用urI 路径 如 api/v1/users

2、使用查询字符串，如 api/users?version=v1

3、使用自定义消息头，如Accept-version:v1

4、使用Accept消息头，如Accept:application/json;v=2.0

文章来源: codeboy.blog.csdn.net，作者：愚公搬代码，版权归原作者所有，如需转载，请联系作者。

原文链接：codeboy.blog.csdn.net/article/details/108458405