github restful api v3学习梳理
来源:互联网 发布:java游戏编程入门pdf 编辑:程序博客网 时间:2024/05/16 08:33
github做的比较好的地方
- 文档写的好,对资源的从属分类做的特别好,让人一眼就知道大致在做什么;
- 对各种接口的变迁有对象的描述,也有对应的解决方案;add-team-member 和 add-or-update-team-membership 都是在teams中,增加一个成员,但是membership就像是对member的一个升级版本,前者当在
teams
中邀请成员的时候,如果该用户不存在在orgs
中,就会返回相应的状态码,相当于报错。但是后者就做到了平滑的升级,当用户不存在在orgs
中的时候就发一封邮件给这个用户,然后把这个用户的状态设置为penging
,当用户同意加入teams
的时候就把该用户的状态设置为actived
- 如果调用不同版本的接口, 或者使用其他的数据格式(不是json)的接口可以通过
http
的Accept
头部字段进行制定; - 更加安全:如果外部访问的内部不开放的资源,不会返回401(Unauthorized),会返回404,这是为了不让攻击者轻易找到内部的资源
- 使用缓存, 以
events
这个资源为例子,如果在缓存时间内没有新的event
被触发,那么服务端会返回的是304(Not Modified) - 对发起请求的角色的请求进行限流操作,减少服务器压力,【rate-limit】, 【rate-limiting】
- 合理的使用状态码
- /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/membersDELETE /orgs/:org/members/:usernamePUT /orgs/:org/memberships/:usernamePOST /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字段。
遗留的问题
- 什么场景用add什么场景用create
- 什么场景用remove什么场景用delete
- 什么场景用edit什么场景用update
阅读全文
1 0
- github restful api v3学习梳理
- 跟着 Github 学习 Restful HTTP API 设计
- Github API v3 -Overview
- Github API v3-OAuth
- RESTful-github.api 介绍
- Github API v3-OAuth Authorizations API
- RESTFUL API学习教程
- Restful API学习笔记
- RESTful API 学习笔记
- Github API v3-Overview-Media Types
- YII2 学习笔记-- RESTFUL API
- Python RESTful API 学习(一)
- Spring Boot学习(RESTful API)
- springboot学习笔记(三) Restful API
- flask RESTful api学习 WITH POSTMAN调试
- RestFul API
- RESTful API
- RESTful API
- Mac vmWare 找不到可以连接的有效对等进程
- 第一次使用maven创建web项目
- SQL 语法
- eclipse Clean 项目不生成class文件
- 代码创建 UI 组件时出现的错误 UILayoutConstraint translatesAutoresizingMaskIntoConstraints: Bool
- github restful api v3学习梳理
- Composer设置忽略版本匹配的方法
- linux进程管理
- LeetCode 328. Odd Even Linked List
- Mysql INT类型最大值探讨
- 登陆窗口进阶版
- sqlServer 更新一列为行号问题
- java运用itextpdf实现根据模板生成合同并返回网络路径,供用户查看
- How to install the Guake Terminal