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)的接口可以通过httpAccept头部字段进行制定;
  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我们可以得到这个usergistsorgsrepos等信息,下图展示了以user为中心怎么对应资源进行操作。

github restful api v3学习梳理_第1张图片


issues

github restful api v3学习梳理_第2张图片

repos

github restful api v3学习梳理_第3张图片


teams

github restful api v3学习梳理_第4张图片

orgs

github restful api v3学习梳理_第5张图片

获取资源的方式

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


你可能感兴趣的:(github restful api v3学习梳理)