[01] 浅谈RESTful风格的API


1、什么是RESTful风格的API

REST,即Representational State Transfer,可以理解为“(资源的)表现层状态转化”。

在网络上,我们通过浏览器输入url,来访问和获取到所需要的资源。这里的url,是对资源位置的定位描述,其实也是一种资源的具体呈现的方式,即这里所说的“表现层”。我们访问资源的过程涉及到数据和状态的变化,“建立在表现层(url)基础上使资源状态发生变化”,也即“表现层状态转化(REST)”了。

符合REST规范的API,则称之为RESTful风格的API,再大白话一点,能让我们“通过API接口名称就能明白它的作用”,它优雅、规范、易懂,省去了许多无意义的沟通和文档。核心规范是什么呢?使用HTTP协议中的四种不同请求方式,来代表四种不同的动词操作:GET用来获取资源;POST用来新建资源;PUT用来更新资源;DELETE用来删除资源。

具体一点来说,RESTful API有如下特点
  • 基于“资源”,数据也好,服务也好,在RESTful设计中一切都是资源
  • 每个URL表示一种资源
  • URL语义清晰明确,不出现动词,只有名词(操作的动词是通过请求方式来表示)
  • 使用HTTP的 POST、DELETE、PUT、GET 来表示对资源的增删改查
  • 尽量使用JSON而不是XML
  • 应该将API的版本号放入URL

举例来说,某API提供动物园(zoo)系统相关信息,则RESTful的API风格如下:
  • https://api.example.com/v1/zoos
  • https://api.example.com/v1/animals
  • https://api.example.com/v1/employees

再具体一点:
  • GET        /zoos:列出所有动物园
  • POST      /zoos:新建一个动物园
  • GET        /zoos/ID:获取某个指定动物园的信息
  • PUT        /zoos/ID:更新某个指定动物园的信息
  • GET        /zoos/ID/animals:列出某个指定动物园的所有动物
  • DELETE  /zoos/ID/animals/ID:删除某个指定动物园的指定动物

API同时也可以提供一些参数,用来过滤返回结果,常见参数如下:
  • ?limit=10:指定返回记录的数量
  • ?offset=10:指定返回记录的开始位置。
  • ?page=2&per_page=100:指定第几页,以及每页的记录数。
  • ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
  • ?animal_type_id=1:指定筛选条件

再来一个鲜活的例子,豆瓣图书相关的开发API
[01] 浅谈RESTful风格的API

先看看这个链接,是什么作用?再试试直接访问(GET方式),返回的内容是什么?https://api.douban.com/v2/book/1220563
 

2、RESTful什么时候好用

对于开放的API,豆瓣、新浪微博、GitHub,好用,非常合适;对于内部开发,不好用。

基于资源型的RESTful API 接口粒度和返回结果过于的“粗”,它通常返回的都是完整的数据模型,这对于客户端非常不友好。但开放API之所以开放,就是因为它不知道你到底需要什么返回结果,既然不知道,那么我干脆都返回给你。这样的好处是通用,但客户端不好处理。你只需要一个字段,服务器却丢给你十几个,作为客户端开发者你怎么想?

内部开发由于需求非常明确,通常来说服务器是不应该简单粗暴的直接甩资源实体给客户端的。那RESTful API就不能接入到内部开发吗?当然不是,我们需要灵活一些借鉴RESTFul中的优点,来设计我们的内部API。那么如何简化,就需要自己去琢磨和体会了。

3、参考链接



上一篇:关于虹软人脸识别SDK的接入


下一篇:Linux内核参数