github restful api v3学习梳理

github做的比较好的地方

1. 文档写的好,对资源的从属分类做的特别好，让人一眼就知道大致在做什么；
2. 对各种接口的变迁有对象的描述，也有对应的解决方案；add-team-member 和 add-or-update-team-membership 都是在teams中，增加一个成员，但是membership就像是对member的一个升级版本，前者当在teams中邀请成员的时候，如果该用户不存在在orgs中，就会返回相应的状态码，相当于报错。但是后者就做到了平滑的升级，当用户不存在在orgs中的时候就发一封邮件给这个用户，然后把这个用户的状态设置为penging，当用户同意加入teams的时候就把该用户的状态设置为actived
   
3. 如果调用不同版本的接口, 或者使用其他的数据格式(不是json)的接口可以通过http的Accept头部字段进行制定；
   
4. 更加安全：如果外部访问的内部不开放的资源，不会返回401（Unauthorized），会返回404，这是为了不让攻击者轻易找到内部的资源
5. 使用缓存， 以events这个资源为例子，如果在缓存时间内没有新的event被触发，那么服务端会返回的是304（Not Modified）
6. 对发起请求的角色的请求进行限流操作，减少服务器压力，【rate-limit】， 【rate-limiting】
7. 合理的使用状态码

• /orgs/:org/members 成功返回200，如果请求者不是该组织的成员会重定向(302)到/orgs/:org/public_members
• /orgs/:org/members/:username这个接口的作用是校验该用户是不是该组织下的成员，如果是的话返回204(请求处理成功，但没资源返回)，如果org争取但是username不正确那么返回404，如果org错误就会重定向到check-public-membership

各个资源之间的关系

梳理了github主要的资源以及对资源的操作

概览图

上图主要描述的是资源之间的"从属"关系图，这里的从属是一种“可以”的关系，不是一种“必须“的关系，比如通过user -> orgs，要获取orgs不一定是要通过user，也可以通过其他方式，比如get-an-organization。

资源关系描述

user

从总览图中我们知道，通过user我们可以得到这个user的gists，orgs，repos等信息，下图展示了以user为中心怎么对应资源进行操作。

issues

repos

teams

orgs

search

获取资源的方式

github v3的api遵循了restful api资源是核心的理念，所有的操作都是针对资源进行处理的。

而资源是通过URI表示出来的，所以怎么URI的结构化，易懂就是设计api的核心。以github api中的orgs进行举例说明：

• GET /orgs/:org/members
• DELETE /orgs/:org/members/:username
• PUT /orgs/:org/memberships/:username
• POST /orgs/:org/teams

通过资源的嵌套

• /users/:username/repos
• /orgs/:org/repos
• /repos/:owner/:repo

放在请求参数里面

• /search/repositories?q = string&sort=data&order=sec
• /orgs/:org/members?filter=all&role=admin

通过资源的嵌套，以URI的形式来表示资源之间的关系。

一些不能表示资源的就可以放在请求参数里面，也就是说放在请求参数中的一般是没有资含义的，比如说Pagination

错误处理

如果发生请求错误的话，在请求体中给出相应的信息。client-errors

{ "message": "Validation Failed", "errors": [ { "resource": "Issue", "field": "title", "code": "missing_field" } ] }

如果只是用状态码表示的话，会显得反馈信息比较模糊。

响应的格式

在v3版本中返回的数据格式是JSON的数据格式，数据是直接返回，如果想返回其他的数据格式可以通过http请求头中的accept字段。

遗留的问题

1. 什么场景用add什么场景用create
2. 什么场景用remove什么场景用delete
3. 什么场景用edit什么场景用update