restful的API架构风格和例子

restful是一种风格,这个风格是需要在一个空无的条件下形成一系列约束形成的。

全名是representational state transfer:表现层状态转换

restful出现是为了保证在大型或者分布式的架构上保证每个组件都能独自的运行或者修改进化。

restful的约束:

1.客户端和服务器的分离

2.无状态,消除session会话,所以在每次交互的时候会有大量的数据在请求中,客户端也需要维护自己的状态,这样就节省很多资源。

3.统一的资源接口/界面:web之间的交互意味着客户端和服务器和他们之间的中介程序都依赖于接口的统一性

①资源的标识,这里指的是uri

②统过表述对资源进行操纵:这个一般是crud

例子:当获取到某个api时可以同过修改uri进行修改或删除这个api的内容

③带着自我描述性的信息

④超媒体作为应用的程序状态引擎

例子:用户通过点击跳转页面时会导致客户端发生变化,这些变化是超文本的修改,超媒体就是超文本泛化说法,超媒体是告诉客户端如何使用api。

4.多层架构

5.可缓存

6.按需编码(可选约束)

Richardson成熟的模型

评价restfulapi的成熟度。理查德森评估模型

level0:POX(plain old xml)

例子:

post(查询数据):http://host/myapi

psst(创建数据):http://host/myapi

 这是只是使用http协议,糟糕的的设计,uri只有一个,这种很难维护,而且动词也使用错了

level1:Resources

例子:

post: http://host/api/author

post:http://host/api/authors/{id}

使用了不同的uri,相当于资源的定位是正确的,但是请求的动词不正确,

level2:Http verbs

get:http://host/api/authors 200 ok (authors) 

post:(author respresentation) http://host/api/authors 201 created(author)

这里动词使用正确,并且有统一的uri,这已经是一个不错的api,但是还打不到真正的restful

level3:Hypermedia Controls

get:http://host/api/authors 200 ok(返回了authors和驱动的应用程序的超链接)

API对外合约

api的消费者需要使用三个概念

1.资源标识

2.http方法

3.有效载荷(可选)

资源的命名,使用名词,而不是动词

需求:获取用户系统里的用户常见的错误做法是:api/getusers.

分析:这句话主要动词是获取,而想要获取资源的是用户

正确做法:GET api/users

能够一眼就明白

需求:获取用户

可以吧uri设计成api/u或者api/ur

建议是用api/users

体现出资源的结构性

假设api系统有很多资源,而用户资源与其他资源没有直接的关系,这样的话获取资源的uri应该是api/uers,而不是api/products/users,也不是api/catalogs/products/users

因为user和product或者catalogs都没直接关系

通过id获取单个用户的uri应该:api/users/{userID},而不是api/userID/users

这样写的好处是让API具有很好的资源预测性和一置性。

例子:

需求:系统有两类资源,公司和员工心在回去某个公司下所有员工信息

分析:使用GET动词,API的uri在设计的时候需要体现公司和员工包含关系

常见错误做法:api/employess,api/employess/{companyID}

正确做法:GET api/companies/{companyID}/employess

例子:

需求:获取某个公司的某个员工信息

常见的错误做法:api/employess/{employeeID},或者api/companies/{employeeID}

正确做法:api/companies/{companyID}/employees/{employeeID}

例子:

需求:获取素有用户,并且结果按照年龄的从小到大排序

常见的错误做法:api/users/orderby/age

正确做法:api/users?orderby=name

例子:

需求:获取用户的数量

总有一些需求,没法满足restful的约束,如果users取出在计算就很浪费资源

妥协做法:api/users/totalamountofuser

原文地址:https://www.cnblogs.com/liuyang95/p/13140360.html