RESTful设计原则和样例（开发先后台接口）

时间 2019-11-05

标签 restful 设计原则样例开发后台接口繁體版

原文原文链接

参考博文： http://www.cnblogs.com/artech/p/restful-web-api-02.html
php

维基百科：https://zh.wikipedia.org/wiki/RESThtml

目前在三种主流的Web服务实现方案中，由于REST模式与复杂的SOAP和XML-RPC相比更加简洁，愈来愈多的web服务开始采用REST风格设计和实现。例如，Amazon.com提供接近REST风格的Web服务进行图书查找；雅虎提供的Web服务也是REST风格的。web

要点及标准

须要注意的是，REST是设计风格而不是标准。REST一般基于使用HTTP，URI，和XML以及HTML这些现有的普遍流行的协议和标准。api

资源是由URI来指定。数组
对资源的操做包括获取、建立、修改和删除资源，这些操做正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。浏览器
经过操做资源的表现形式来操做资源。缓存
资源的表现形式则是XML或者HTML，取决于读者是机器仍是人，是消费web服务的客户软件仍是web浏览器。固然也能够是任何其余的格式。安全

REST的要求

客户端和服务器结构服务器
链接协议具备无状态性restful
可以利用Cache机制增进性能
层次化的系统
所需代码 - Javascript （可选）

关于状态

应该注意区别应用的状态和链接协议的状态。HTTP链接是无状态的（也就是不记录每一个链接的信息），而REST传输会包含应用的全部状态信息，所以能够大幅下降对HTTP链接的重复请求资源消耗。

应用于 Web 服务

符合 REST 设计风格的 Web API 称为 RESTful API。它从如下三个方面资源进行定义：

直观简短的资源地址：URI，好比：http://example.com/resources/。
传输的资源：Web服务接受与返回的互联网媒体类型，好比：JSON，XML ，YAML 等。
对资源的操做：Web服务在该资源上所支持的一系列请求方法（好比：POST，GET，PUT或DELETE）。

下表列出了在实现 RESTful API 时 HTTP 请求方法的典型用途。

^[1] HTTP 请求方法在 RESTful API 中的典型应用

资源	GET	PUT	POST	DELETE
一组资源的URI，好比`http://example.com/resources/`	列出 URI，以及该资源组中每一个资源的详细信息（后者可选）。	使用给定的一组资源替换当前整组资源。	在本组资源中建立/追加一个新的资源。该操做每每返回新资源的URL。	删除整组资源。
单个资源的URI，好比`http://example.com/resources/142`	获取指定的资源的详细信息，格式能够自选一个合适的网络媒体类型（好比：XML、JSON等）	替换/建立指定的资源。并将其追加到相应的资源组中。	把指定的资源当作一个资源组，并在其下建立/追加一个新的元素，使其隶属于当前资源。	删除指定的元素。

PUT 和 DELETE 方法是幂等方法。GET方法是安全方法（不会对服务器端有修改，所以固然也是幂等的）。

不像基于SOAP的Web服务，RESTful Web服务并无的“正式”标准^[2]。这是由于REST是一种架构，而SOAP只是一个协议。虽然REST不是一个标准，但在实现RESTful Web服务时可使用其余各类标准（好比HTTP，URL，XML，PNG等）。

实现举例[编辑]

例如，一个简单的网络商店应用，

列举全部商品，

GET http://www.store.com/products

呈现某一件商品，

GET http://www.store.com/product/12345

下单购买，

POST http://www.store.com/order
<purchase-order>
  <item> ... </item1>
</purchase-order>

REST的优势

可更高效利用缓存来提升响应速度
通信自己的无状态性可让不一样的服务器的处理一系列请求中的不一样请求，提升服务器的扩展性
浏览器便可做为客户端，简化软件需求
相对于其余叠加在HTTP协议之上的机制，REST的软件依赖性更小
不须要额外的资源发现机制
在软件技术演进中的长期的兼容性更好

默认全部输入输出均为JSON格式。一个例外：GET请求的参数为URL参数
出错代码一概使用HTTP标准错误码，参见HTTP 标准状态码

修改用户：

URL: POST /mm/v1/crm/customer/[customer id]
输入：
参数名参数类型说明必填默认值限制
name string 客户名称是
interface_person string 对接人姓名是
interface_phonenumber string 对接人电话是
interface_email string 对接人邮箱是

输出：
参数名参数类型说明样例值
id int 客户ID 10001
name string 客户名称银行
interface_person string 对接人姓名小明
interface_phonenumber string 对接人电话 12345678
interface_email string 对接人邮箱 misdfu@asdfasdf.com
create_time date 客户建立时间 2015-04-01 12:34:56

得到全部可编辑权限
URL: GET /mm/v1/crm/permission
输入
输出
一个数组。每一个元素表明一个可编辑的权限项，格式以下
参数名参数类型说明样例值
id int 权限ID 1
name string 权限名称 DEMO APP

删除用户

URL：DELETE /mm/v1/crm/customer/[customer id]输入：无输出：参数名参数类型说明样例值id int 成功删除的客户ID 10001