前言

近日在搭建个人博客后台。自然而然逃避不了设计api。选用RESTful API设计风格。
其实，一些实践已经有太多文章讲述了。这里仅对其中几点做个说明。

正文

首先大致说下api俩种方式传递的数据：层级数据（hierarchical data）和非层级数据（non-hierarchical data也就是标识资源）。
来个例子。比如获取某个用户的某篇文章：/api/v1/users/:owner_id/articles/:article_id?fields=title,content。这里的:owner、:article是层级数据，fields=title,content是标识资源。

疑问几点

层级数据多余

就像获取某个用户的某篇文章：/api/v1/users/:owner_id/articles/:article_id，这里的:article_id是唯一的，也就是可以直接定位到具体的那篇文章，为何需要:owner_id。其实这里把规范看的太死，/api/v1/articles/:article_id就行了，这里将articles当做独立得资源即可。

层级数据or非层级数据

比如根据文章名获取某个用户的某篇文章。他有俩种设计

1. /api/v1/users/:owner_id/articles?article_name
2. /api/v1/users/articles?article_name=xxx&user_id=xxx
   到底哪个好呢？个人觉得其实没有好坏之分。主要得看应用场景还有得设计的易懂，一目了然。
   前者把用户当做层级数据，后者认为用户与文章俩者没有很强的层级关系。
   值得注意的是，一般而言末端资源可以用非层级数据详尽描述。

Github REST API部分疑惑

1. 获取你的仓库：GET /user/repos。注意这里user是单数，因为指代你自己一个人且不用指定你的用户名或者id像是/user/:your_id/repos。因为这在token里就可以了。
2. 根据用户来获取其所有仓库：GET /users/:username/repos。与前者不同的是users是复数，因为指代所有用户。
3. 根据用户来获取具体某个仓库：GET /repos/:owner/:repo。这点其实原本我是有疑虑的。因为没看见之前啊我是觉得应该是/users/:owner/repos/:repo。但是看见了github设计的想了下感觉它的更合理。因为本能的觉得repo依赖于user，所以设计成我那样子，其实repo是可以独立存在的。当然我这个也没错，但是如果层级深了，比如族谱，那就不合适了。当然这俩层不深，感觉看个人喜欢。还有的是这里的:owner是用户名，是唯一的，但是:repo不是，所以呢就需要指定下:owner。但是如果:repo是唯一的，:owner就明显没必要了。/repos/:repo就可以了。

博客API设计

PS:原本还想加上认证、标签、分类，想想还是不加了，感觉重复工作，索然无味。对了，如果根据标签获取文章，标签作为标志资源即可。

因为上边个人博客，只是个人使用，所以不全，以下添加俩条