restful接口用在c s架构下吗（restful api接口规范）

本文目录

• restful api接口规范
• 什么是 restful
• 什么是RESTful风格的API
• RESTful 架构 （表现层状态转移）
• 有没有方便开发RESTful api 的c++库

restful api接口规范

restful api接口规范如下：

1、协议

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

2、域名

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

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

3、版本（Versioning）

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

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

4、路径（Endpoint）

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

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

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

什么是 restful

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。RESTful架构是对MVC架构改进后所形成的一种架构，通过使用事先定义好的接口与不同的服务联系起来。在RESTful架构中，浏览器使用POST，DELETE，PUT和GET四种请求方式分别对指定的URL资源进行增删改查操作。因此，RESTful是通过URI实现对资源的管理及访问，具有扩展性强、结构清晰的特点。RESTful架构将服务器分成前端服务器和后端服务器两部分，前端服务器为用户提供无模型的视图；后端服务器为前端服务器提供接口。浏览器向前端服务器请求视图，通过视图中包含的AJAX函数发起接口请求获取模型。项目开发引入RESTful架构，利于团队并行开发。在RESTful架构中，将多数HTTP请求转移到前端服务器上，降低服务器的负荷，使视图获取后端模型失败也能呈现。但RESTful架构却不适用于所有的项目，当项目比较小时无需使用RESTful架构，项目变得更加复杂。

什么是RESTful风格的API

REST -- REpresentational State Transfer 首先，之所以晦涩是因为前面的主语被去掉了，全称是 Resource Representational State Transfer，通俗来讲就是：资源在网络中以某种表现形式进行状态转移。 分解开来： Resource：资源，即数据（前面说过网络的核心）。比如 newsfeed，friends等； Representational：某种表现形式，比如用JSON，XML，JPEG等； State Transfer：状态变化。通过HTTP动词实现。 大家都知道“古代”网页是前端后端融在一起的，比如之前的PHP，JSP等，在之前的桌面时代，前后端融合在一起没啥问题，但是近年来移动互联网的发展，各种类型的Client层出不穷，RESTful可以通过一套统一的接口为Web、iOS、Android、小程序等提供接口API服务。另外对于广大平台来说，比如Facebook platform，微博开放平台，微信公共平台等，它们不需要有显式的前端，只需要一套提供服务的接口，于是RESTful的API更是它们最好的选择。 根据Richardson Maturity Model（理查德森成熟度模型）, REST架构的成熟度有4个等级： 我们在咖啡店向前台点了一杯拿铁咖啡，这个过程可以用这段文字来描述： 我们通过这段文字告诉前台，新增一笔订单，订单是一杯拿铁咖啡，接着，前台给我们返回这么一串回复： 假设我们有一张会员卡，我们想查询一下这张会员卡的余额，这时候要向前台发起另一个询问： 查询卡号为447031335的卡的余额，查询的结果返回来了： 没钱……哈哈哈，没钱，现在我们要跟前台说，这杯咖啡不要了： 现在这家咖啡店越做越大，来喝咖啡的人越来越多，单靠前台显然是不行的，店主决定进行分工，每个资源都有专人负责，我们可以直接面向资源操作。 比如还是下单，请求的内容不变，但是我们多了一条消息: 多了一个斜杠和orders，这是什么意思？ 这个表示我们这个请求是发给哪个资源的，订单是一种资源，我们可以理解为是咖啡厅专门管理订单的人，他可以帮我们处理所有有关订单的操作，包括新增订单、修改订单、取消订单等操作。 接着还是会返回订单的编号给我们： 下面，我们还是要查询会员卡余额，这次请求的资源变成了cards： 接下来是取消订单： 接下来，店主还想继续优化他的咖啡厅的服务流程，他发现负责处理订单的员工，每次都要去订单内容里面看是新增订单还是删除订单，还是其他的什么操作，十分不方便，于是规定，所有新增资源的请求，都在请求上面写上大大的“POST”，表示这是一笔新增资源的请求。 其他种类的请求，比如查询类的，用‘GET’表示，删除类的，用‘DELETE’表示，修改用PATCH表示。 来，我们再来重复上面那个过程，来一杯拿铁： 请求的内容简洁多啦，不用告诉店员是addOrder，看到POST就知道是新增，返回的内容还是一样： 接着是查询会员卡余额，这次也简化了很多： 这个请求我们还可以进一步优化为这样： 直接把要查询的卡号写在后面了。 没错，接着，取消订单： 忽然有一天，有个顾客抱怨说，他买了咖啡后，不知道要怎么取消订单，咖啡厅一个店员回了一句，你不会看我们的宣传单吗，上面不写着： 顾客反问道，谁会去看那个啊，店员不服，又说到，你瞎了啊你……后面两人吵着吵着还打了起来… 噗，真是悲剧… 有了这次教训，店长决定，顾客下了单之后，不仅给他们返回订单的编号，还给顾客返回所有可以对这个订单做的操作，比如告诉用户如何删除订单。现在，我们还是发出请求，请求内容和上一次一样： 但是这次返回时多了些内容： 这次返回时多了一项link信息，里面包含了一个rel属性和url属性，rel是relationship的意思，这里的关系是cancel，url则告诉你如何执行这个cancel操作，接着你就可以这样子来取消订单啦： 哈哈，这服务真是贴心，以后再也不用担心店员和顾客打起来了。 Level 3的Restful API，给使用者带来了很大的便利，使用者只需要知道如何获取资源的入口，之后的每个URI都可以通过请求获得，无法获得就说明无法执行那个请求。***隐藏网址*** Level 1 解释了如何通过分治法(Divide and Conquer)来处理复杂问题，将一个大型的服务端点(Service Endpoint)分解成多个资源。 Level 2 引入了一套标准的动词，用来以相同的方式应对类似的场景，移除不要的变化。 Level 3 引入了可发现性(Discoverability)，它可以使协议拥有自我描述(Self-documenting)的能力。 这一模型帮助我们思考我们想要提供的HTTP服务是何种类型的，同时也勾勒出人们和它进行交互时的期望。 ❶ REST描述的是在网络中client和server的一种交互形式；REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）； ❷ Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心， URL定位资源，用HTTP动词（GET/POST/DELETE/PATCH）来描述操作， ❸ 用HTTP协议里的动词来实现资源的添加、修改、删除等操作。即通过HTTP动词来实现资源的状态转移： ❹ Server和Client之间传递某资源的一个表现形式，比如用JSON，XML传输文本，或者用JPG，WebP传输图片等。当然还可以压缩HTTP传输时的数据（on-wire data compression）; ❺ 用 HTTP Status Code传递Server的状态信息。比如最常用的 200 表示成功，500 表示Server内部错误等。 好了，理解了RESTful的概念，究竟如何应用，这是个问题。根据项目的需求不同，我们的API设计规范也存在差别，完全看自身理解，满足自身需求，大的理念不变，根据需求制定项目的API规范就是好的RESTful。

RESTful 架构 （表现层状态转移）

概念是 Roy Thomas Fielding在他2000年的博士论文中提出的。他参与制定了 HTTP 1.0 和 HTTP 1.1 协议。 他希望能基于网络现有的协议基础上创建一个功能强大，性能游戏，适宜通信的架构。 如含义一样，将从逻辑上将业务实现拆分为客户端与服务端实现。 通过分离设计，能简化两边的设计复杂度，提高其可扩展性。 资源是 RESTful 的主体，主要指代互联网上的一个实体，可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。资源通过 URI 来唯一标识。 资源的信息载体形式，叫做表现层。他可以是文本、XML、JSON 或者是一个二进制文件。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。 互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。 在 HTTP 中，我们一般通过四种 HTTP 动词（verb）来对应资源的变化：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。 相应的状态的交互应当是无状态的（ServerLess）这是 HTTP 的特性所决定的，要求每次请求包含服务器需要的所有信息，这样可以很好的确保每一次变化的可预测性，进而提高可靠性，也能增进可扩展性。 综合上面的解释，我们总结一下什么是RESTful架构： （1）每一个URI代表一种资源； （2）客户端和服务器之间，传递这种资源的某种表现层； （3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。 HTTP 请求是互联网架构中重要的一环，其在 TCP 连接的基础上，实现了语义化，缓存机制，无状态等等特性。在互联网上也有不错的性能，REST 常常会基于 HTTP 协议的基础上实现其核心概念。 论文中对 HTTP 与 REST 相适宜的论述提及了几点： 这里是论文中对 HTTP Code 来表现业务相应状态的相关表述： ***隐藏网址*** 他讲这个模型层次分为四级，大概如下所示： 利用 HTTP 协议做数据交换，所有的参数描述通过 url 或者 POST body 形式通知服务器，返回相应的数据，此级别通常都是基于 。实质上就是基于 HTTP 的 RPC（远程过程调用），具体交付的细节完全由相关规范或团队内部约定解决。 根据理解设计了一份请求交互： 将 API 按照 RESTful 中资源的方式进行划分，初步有了自我描述（self description）的特性了，客户端可以对相关的资源进行更加细致的操作。 根据理解设计了一份请求交互： 这个级别有更加进一步的利用了 HTTP 的特性，增加了对 HTTP verb （比如 GET 表示查询、POST 表示创建、PUT 表示修改、DELETE 表示 等等）的运用，并且运用原有的 HTTP response status 来表征业务上请求的成功与失败，一般项目常见的 RESTful 运用基本都接近这个级别。 这个请求基本就和我们平时使用的 RESTful api 很接近了： 这个基本也称作 HATEOAS (Hypertext As The Engine Of Application State)，这个级别是 RESTful 最复杂的实现，这个级别最理想的情况是，不需要特别复杂 API 文档进行描述的，这里的 API 设计最大化的实现了 RESTful 的自我描述特性。这种方案虽然引入很大的复杂性，但是最大限度的将 API 设计变得配置化了，所有 API 设计将会基于更加抽象的工作流设计了，稍后再做解释： 本阶段的相关请求模型大概是这样的： 可以看出，从查询到最终结果，都是由第一个 api 的返回的资源列表和操作项，引导向后面的操作，这样，后端在设计 API 的时候，需要考虑从一条业务 workflow 的角度去设计。这样只要整个流程不变，局部的数据变化，只需要修改后端的相关配置即可，这样业务可以很大程度的配置化。

有没有方便开发RESTful api 的c++库

　　一个好的RESTful API，应该具备以下特征：　　这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。　　1.浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。　　这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。　　REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。　　按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。　　2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。　　这个API应该是松耦合的。　　RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。　　3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。　　这个API中所使用的表述格式应该是常见的通用格式　　在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。　　4.这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。　　使用HTTP响应状态代码来表达各种出错情况　　HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。　　5.如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。　　这个API应该对于HTTP缓存是友好的　　6.充分利用好HTTP缓存是RESTful API可伸缩性的根本。HTTP协议是一个分层的架构，从两端的user agent到origin server之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。