模仿 Github,设计一个博客网站的 API
认证方式
有两种方法可以通过GitHub API v3进行身份验证。需要身份验证的请求在某些地方将返回404 Not Found
,而不是 403 Forbidden
。这是为了防止私有存储库意外泄露给未经授权的用户。
curl -u“用户名” https://api.github.com
OAuth2令牌(在标头中发送)
curl -H“授权:令牌OAUTH-TOKEN ” https://api.github.com
登录限制失败
使用无效的凭据进行身份验证将返回401 Unauthorized
:
curl -i https://api.github.com -u foo:bar
HTTP / 1.1 401未经授权的
{
“ message”:“错误的凭据”,
“ documentation_url”:“ https://developer.github.com/v3”
}
在短时间内检测到多个具有无效凭据的请求后,API会临时拒绝该用户的所有身份验证尝试(包括具有有效凭据的请求)403 Forbidden
:
curl -i https://api.github.com -u valid_username:valid_password
HTTP / 1.1 403禁止
{
“ message”:“已超过最大登录尝试次数。请稍后再试。”,
“ documentation_url”:“ https:/ /developer.github.com/v3“
}
参量
许多API方法采用可选参数。对于GET请求,任何未在路径中指定为段的参数都可以作为HTTP查询字符串参数传递:
curl -i“ https://api.github.com/repos/vmg/redcarpet/issues?state=closed”
在查询字符串中传递路径时,为路径中的:owner
和:repo
参数提供了’vmg’和’redcarpet’值:state
。
为POST
,PATCH
,PUT
,和DELETE
的要求,不包含在URL参数应当被编码为JSON与“应用/ JSON”的内容类型:
curl -i -u用户名-d'{“ scopes”:[“ public_repo”]}'https://api.github.com/authorizations
根端点
您可以GET
向根端点发出请求,以获取REST API v3支持的所有端点类别:
卷曲https://api.github.com
使用 Method
VERB | 描述 |
---|---|
HEAD | 只获取某个资源的头部信息。比如只想了解某个文件的大小,某个资源的修改日期等 |
GET | 获取资源 |
POST | 创建资源 |
PATCH | 更新资源的部分属性。因为 PATCH 比较新,而且规范比较复杂,所以真正实现的比较少,一般都是用 POST 替代 |
PUT | 替 |
DELETE | 删除资源 |
例如:
GET /repos/:owner/:repo/issues
GET /repos/:owner/:repo/issues/:number
POST /repos/:owner/:repo/issues
PATCH /repos/:owner/:repo/issues/:number
DELETE /repos/:owner/:repo
选择状态码
状态码 | LABEL | 解释 |
---|---|---|
200 | OK | 请求成功接收并处理,一般响应中都会有 body |
201 | Created | 请求已完成,并导致了一个或者多个资源被创建,最常用在 POST 创建资源的时候 |
202 | Accepted | 请求已经接收并开始处理,但是处理还没有完成。一般用在异步处理的情况,响应 body 中应该告诉客户端去哪里查看任务的状态 |
204 | No Content | 请求已经处理完成,但是没有信息要返回,经常用在 PUT 更新资源的时候(客户端提供资源的所有属性,因此不需要服务端返回)。如果有重要的 metadata,可以放到头部返回 |
301 | Moved Permanently | 请求的资源已经永久性地移动到另外一个地方,后续所有的请求都应该直接访问新地址。服务端会把新地址写在 Location 头部字段,方便客户端使用。允许客户端把 POST 请求修改为 GET。 |
304 | Not Modified | 请求的资源和之前的版本一样,没有发生改变。用来缓存资源,和条件性请求(conditional request)一起出现 |
307 | Temporary Redirect | 目标资源暂时性地移动到新的地址,客户端需要去新地址进行操作,但是不能修改请求的方法。 |
308 | Permanent Redirect | 和 301 类似,除了客户端不能修改原请求的方法 |
400 | Bad Request | 客户端发送的请求有错误(请求语法错误,body 数据格式有误,body 缺少必须的字段等),导致服务端无法处理 |
401 | Unauthorized | 请求的资源需要认证,客户端没有提供认证信息或者认证信息不正确 |
403 | Forbidden | 服务器端接收到并理解客户端的请求,但是客户端的权限不足。比如,普通用户想操作只有管理员才有权限的资源。 |
404 | Not Found | 客户端要访问的资源不存在,链接失效或者客户端伪造 URL 的时候回遇到这个情况 |
405 | Method Not Allowed | 服务端接收到了请求,而且要访问的资源也存在,但是不支持对应的方法。服务端必须返回 Allow 头部,告诉客户端哪些方法是允许的 |
415 | Unsupported Media Type | 服务端不支持客户端请求的资源格式,一般是因为客户端在 Content-Type 或者 Content-Encoding 中申明了希望的返回格式,但是服务端没有实现。比如,客户端希望收到 xml返回,但是服务端支持 Json |
429 | Too Many Requests | 客户端在规定的时间里发送了太多请求,在进行限流的时候会用到 |
500 | Internal Server Error | 服务器内部错误,导致无法完成请求的内容 |
503 | Service Unavailable | 服务器因为负载过高或者维护,暂时无法提供服务。服务器端应该返回 Retry-After 头部,告诉客户端过一段时间再来重试 |
参考资料
- Github API v3
- RESTful API 设计指南
- REST接口设计规范