关于REST和Blueprint

##RESTful API

最近在做WLAN精灵的API设计,因为前面一直断断续续的接触RESTful API,在这里系统的整理一下。

RESTful API是指符合REST原则的API设计。

REST : Representational state transfer, introduced and defined in 2000 by Roy Fielding in his doctoral dissertation.

对于Representational state transferWiki上翻译为“含状态传输”,阮一峰老师在理解RESTful架构中翻译为“表现层状态转化”,并且还解释了一下Representational state transfer中的representational

其中,“表现层状态转化”一句省略了主语,表现层其实指的是“资源”(Resources)的表现层。

简单来说,就是把数据信息当做资源(resource),通过不同的方法动词(action)来执行不同的操作。
下面是四种action的解释和举例:

  • GET : 获取以及检索数据

    • /api/robots 获得所有robot的数据
    • /api/robots/search/Astro 搜索一个名为Astrorobot
    • /api/robots/2 根据编号获取robot
  • POST : 添加数据

    • /api/robots 添加一条新的数据
  • PUT : 更新数据
    • /api/robots/2 通过id修改数据
  • DELETE : 删除数据
    • /api/robots/2 通过id删除数据

推荐一些关于RESTful API的网站:


##Blueprint

那么什么是Blueprint呢?Blueprintapiary公司开源的一个API文档编辑工具包,它可以把一些约定的标记转换成非常漂亮的文档,就像是Markdown一样。

Blueprint中,基本遵循RESTful API的设计,API可以想象成是对一个资源(resource)的操作。
一级标签*是分组(Group),表示某种对象资源(resource),比如Gist这种。
二级标签**是某个路径(URI),指一种属性,比如星标star、集合collection、等等
三级标签***是操作action,指针对这种属性的操作,比如获取、删除、编辑、星标。

比如官网案例中的Gist

- Gist             # Group Gist
- Gist ## Gist [/gists/{id}]
- Retrieve ### Retrieve a Single Gist [GET]
- Edit ### Edit a Gist [PATCH]
- Delete ### Delete a Gist [DELETE]
- Gists Collection ## Gists Collection [/gists{?since}]
- List ### List All Gists [GET]
- Create ### Create a Gist [POST]
- Star ## Star [/gists/{id}/star]
- Star ### Star a Gist [PUT]
- Unstar ### Unstar a Gist [DELETE]
- Check ### Check if a Gist is Starred [GET]

推荐一些Blueprint的网站: