前言
近日在搭建个人博客后台。自然而然逃避不了设计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非层级数据
比如根据文章名获取某个用户的某篇文章。他有俩种设计
- /api/v1/users/:owner_id/articles?article_name
- /api/v1/users/articles?article_name=xxx&user_id=xxx
到底哪个好呢？个人觉得其实没有好坏之分。主要得看应用场景还有得设计的易懂，一目了然。
前者把用户当做层级数据，后者认为用户与文章俩者没有很强的层级关系。
值得注意的是，一般而言末端资源可以用非层级数据详尽描述。
Github REST API部分疑惑
- 获取你的仓库：GET /user/repos。注意这里user是单数，因为指代你自己一个人且不用指定你的用户名或者id像是/user/:your_id/repos。因为这在token里就可以了。
- 根据用户来获取其所有仓库：GET /users/:username/repos。与前者不同的是users是复数，因为指代所有用户。
- 根据用户来获取具体某个仓库：GET /repos/:owner/:repo。这点其实原本我是有疑虑的。因为没看见之前啊我是觉得应该是/users/:owner/repos/:repo。但是看见了github设计的想了下感觉它的更合理。因为本能的觉得repo依赖于user，所以设计成我那样子，其实repo是可以独立存在的。当然我这个也没错，但是如果层级深了，比如族谱，那就不合适了。当然这俩层不深，感觉看个人喜欢。还有的是这里的:owner是用户名，是唯一的，但是:repo不是，所以呢就需要指定下:owner。但是如果:repo是唯一的，:owner就明显没必要了。/repos/:repo就可以了。
博客API设计
| 模块 | 描述 | url | method |
|---|---|---|---|
| 文章 | 获取你的文章 | /user/articles | GET |
| 根据文章id获取你的文章 | /user/articles/:id | GET | |
| 获取你的topics文章 | /user/articles/topics | GET | |
| 创建文章 | /user/articles | POST | |
| 修改文章 | /articles/:owner/:article | PUT | |
| 删除文章 | /articles/:owner/:article | DELETE |
PS:原本还想加上认证、标签、分类，想想还是不加了，感觉重复工作，索然无味。对了，如果根据标签获取文章，标签作为标志资源即可。
| 模块 | 描述 | url | method |
|---|---|---|---|
| 根据用户获取文章 | /api/v1/users/:owner/articles | GET | |
| 根据用户以及文章id获取具体文章 | /api/v1/users/:owner/articles/:id | GET |
因为上边个人博客，只是个人使用，所以不全，以下添加俩条
| 模块 | 描述 | url | method |
|---|---|---|---|
| 根据用户获取文章 | /api/v1/users/:owner/articles | GET | |
| 根据用户以及文章id获取具体文章 | /api/v1/users/:owner/articles/:id | GET |
