服务计算--模仿github API用markdown编写设计一个博客网站的部分rest API

最新推荐文章于 2022-06-12 12:29:57 发布

TempterCyn

最新推荐文章于 2022-06-12 12:29:57 发布

阅读量294

点赞数

分类专栏：服务计算

本文链接：https://blog.csdn.net/TempterCyn/article/details/103157231

版权

服务计算专栏收录该内容

10 篇文章 0 订阅

订阅专栏

当前版本

默认情况下，所有https://api.myblog.com接收v1 版本的REST API的请求。我们建议您通过Accept明确请求此版本。

Accept: application/vnd.myblog.v1+json

模式

所有API访问都是通过HTTPS进行的，并且可以通过访问https://api.github.com。所有数据都以JSON的形式发送和接收。

curl -i https://api.myblog.com/users/octocat/orgs
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 18 Nov 2019 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-GitHub-Media-Type: github.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

空白字段用null表示。
所有时间戳以ISO 8601格式返回：

YYYY-MM-DDTHH:MM:SSZ

博客摘要

当您获取资源列表时，响应包括该资源的属性子集。这是资源的“摘要”表示。
示例：获得博客列表时，将获得每个博客的摘要表示。在这里，我们获取博客拥有的存储库列表：

GET /users/username/all

详细表示

当您获取单个资源时，响应通常包括该资源的所有属性。这是资源的“详细”表示。
示例：获得单个博客时，将获得博客的详细表示。在这里，我们获取博客的存储库：

GET /users/username/blog/blogname

认证方式

有两种方法可以通过blog API v1进行身份验证。需要身份验证的请求在某些地方将返回404 Not Found，而不是 403 Forbidden。这是为了防止私有存储库意外泄露给未经授权的用户。

基本认证

curl -u “username” https://api.myblog.com

OAuth2 Token 验证

curl -H “Authorization: token OAUTH-TOKEN” https://api.myblog.com

OAuth2密钥

curl
‘https://api.myblog.com/users/whatever?client_id=xxxx&client_secret=yyyy’

使用您的client_id，client_secret并且不对用户进行身份验证，它只会识别您的OAuth应用程序以增加您的速率限制。权限仅授予用户，而不授予应用程序，并且您将仅取回未经身份验证的用户将看到的数据。因此，您仅应在服务器到服务器方案中使用OAuth2密钥。请勿将OAuth应用程序的客户端机密泄露给用户。

登录限制失败

使用无效的凭据进行身份验证将返回401 Unauthorized：

curl -i https://api.myblog.com -u foo:bar
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.myblog.com/v1"
}

在短时间内检测到多个具有无效凭据的请求后，API会临时拒绝该用户的所有身份验证尝试（包括具有有效凭据的请求）403 Forbidden：

curl -i https://api.myblog.com -u valid_username:valid_password
HTTP/1.1 403 Forbidden
{
  "message": "Maximum number of login attempts exceeded. Please try again later.",
  "documentation_url": "https://developer.myblog.com/v1"
}

参数

许多API采用可选参数。对于GET请求，任何未在路径中指定为段的参数都可以作为HTTP查询字符串参数传递：

curl -i “https://api.myblog.com/repos/vmg/redcarpet/issues?state=closed”

对于POST，PATCH，PUT，和DELETE的要求，不包含在URL参数应当被编码为json与“application/json”的类型：

curl -i -u username -d ‘{“scopes”:[“public_repo”]}’ https://api.myblog.com/authorizations

Root endpoint

您可以GET向根端点发出请求，以获取REST API v1支持的所有端点类别：

curl https://api.myblog.com

Client errors

接收请求正文的API调用上可能存在三种类型的客户端错误：

1.发送无效的JSON将导致400 Bad Request响应。

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Problems parsing JSON"}

2.发送错误类型的JSON值将导致400 Bad Request响应。

HTTP/1.1 400 Bad Request
Content-Length: 40

{"message":"Body should be a JSON object"}

3.发送无效的字段将导致422 Unprocessable Entity 响应。

HTTP/1.1 422 Unprocessable Entity
Content-Length: 149

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

所有错误对象都具有资源和字段属性，以便您的客户端可以知道问题所在。还有一个错误代码，以便知道该字段出了什么问题。这些是可能的验证错误代码：

错误名称	描述
missing	资源不存在
missing_field	尚未设置资源上的必填字段
invalid	字段格式无效
already_exists	另一个资源具有与此字段相同的值

资源还可以发送自定义的验证错误（如果code是custom）。自定义错误将始终具有message描述错误的字段，并且大多数错误还将包括documentation_url指向一些可能有助于您解决错误的内容的字段。

HTTP重定向

API v1在适当的地方使用HTTP重定向。客户应假定任何请求都可能导致重定向。接收HTTP重定向不是错误，客户端应遵循该重定向。重定向响应将具有一个 Location标头字段，其中包含客户端应向其重复请求的资源的URI。

状态码	描述
301	永久重定向，发出请求的URI已被Location标头字段中指定的URI取代，对此资源的此请求以及所有将来的请求都应定向到新URI
302，307	临时重定向，应按Location标头字段中指定的URI逐字重复请求，但客户端应继续将原始URI用于以后的请求

HTTP verbs

API v1尽可能在每个动作中使用适当的HTTP verbs。

verb	描述
HEAD	可以针对任何资源发出以仅获取HTTP标头信息
GET	用于检索资源
POST	用于创建资源
PATCH	用于通过部分JSON数据更新资源
PUT	用于替换资源或集合
DELETE	用于删除资源

Hypermedia

所有资源都可以具有一个或多个*_url链接到其他资源的属性。这些旨在提供显式URL，以便适当的API客户端不需要自己构造URL，并且可以使用uri_template gem之类来扩展这些模板：

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand :all => 1
=> "/notifications?all=1"

>> tmpl.expand :all => 1, :participating => 1
=> "/notifications?all=1&participating=1"

分页

默认情况下，返回多个项目的请求将被分页为30个项目。您可以使用?page参数指定其他页面。对于某些资源，您还可以使用?per_page参数设置最大100的自定义页面大小。

curl’https://api.myblog.com/user/repos?page=2&per_page=100’

链接标题

该链接头包括分页信息：

Link: https://api.myblog.com/user/repos?page=3&per_page=100; rel=“next”,
https://api.myblog.com/user/repos?page=50&per_page=100; rel=“last”

此Link响应标头包含一个或多个Hypermedia链接关系，其中一些可能需要扩展为URI模板。
可能的rel值为：

名称	描述
next	结果的下一页的链接关系
last	最后一页结果的链接关系
first	结果首页的链接关系
prev	前一页结果的链接关系

限速

对于使用基本身份验证或OAuth的API请求，您每小时最多可以进行5000个请求。无论使用了基本身份验证还是OAuth令牌，经过身份验证的请求都与经过身份验证的用户相关联。这意味着，当用户授权的所有OAuth应用程序使用同一用户拥有的不同令牌进行身份验证时，它们每小时共享5000个请求的相同配额。
对于未经身份验证的请求，速率限制允许每小时最多60个请求。未经身份验证的请求与原始IP地址相关联，而不与发出请求的用户相关联。
任何API请求返回的HTTP标头都会显示您当前的速率限制状态：

curl -i https://api.myblog.com/users/octocat
HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

标头名称	描述
X-RateLimit-Limit	每小时允许您发出的最大请求数
X-RateLimit-Remaining	当前速率限制窗口中剩余的请求数
X-RateLimit-Reset	当前速率限制窗口重置的时间，以UTC纪元秒为单位

如果您需要其他格式的时间，则可以使用任意现代编程语言完成工作。例如，如果在Web浏览器上打开控制台，则可以轻松地将重置时间作为JavaScript Date对象获取。

new Date(1372700873 * 1000)
// => Mon Nov 18 2019 13:47:53 GMT-0400 (EDT)

如果超出速率限制，则会返回错误响应：

HTTP/1.1 403 Forbidden
Date: Wed, 20 Nov 2019 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
   "message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
   "documentation_url": "https://developer.myblog.com/v1/#rate-limiting"
}

增加OAuth应用程序的未经身份验证的速率限制

如果您的OAuth应用程序需要以更高的速率限制进行未经身份验证的呼叫，则可以将应用程序的客户端ID和密码作为查询字符串的一部分传递。

curl -i 'https://api.myblog.com/users/whatever?client_id=xxxx&client_secret=yyyy'
HTTP/1.1 200 OK
Date: Wed, 20 Nov 2019 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4966
X-RateLimit-Reset: 1372700873

保持在速率限制之内

如果您使用基本身份验证或OAuth超出了速率限制，则可以通过缓存API响应和使用条件请求来解决此问题。

滥用率限制

为了在GitHub上提供优质的服务，使用API时某些操作可能需要附加费率限制。例如，使用API快速创建内容，主动轮询而不是使用webhook，发出多个并发请求或重复请求计算上昂贵的数据可能会导致滥用率受到限制。滥用率限制无意干扰API的合法使用。您的正常费率限制应该是您定位的唯一限制。
如果您的应用程序触发了此速率限制，您将收到响应：

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Connection: close
{
  "message": "You have triggered an abuse detection mechanism and have been temporarily blocked from content creation. Please retry your request again later.",
  "documentation_url": "https://developer.myblog.com/v1/#abuse-rate-limits"
}

用户代理

所有API请求都必须包含有效的User-Agent标头。没有User-Agent 标题的请求将被拒绝。我们要求您使用GitHub用户名或应用程序名称作为User-Agent标头值。

User-Agent: Awesome-Octocat-App

User-Agent默认情况下，cURL发送一个有效的头。如果您User-Agent通过cURL提供了无效的标头，则会收到403 Forbidden响应：

curl -iH 'User-Agent: ' https://api.myblog.com/meta
HTTP/1.0 403 Forbidden
Connection: close
Content-Type: text/html
Request forbidden by administrative rules.
Please make sure your request has a User-Agent header.
Check https://developer.myblog.com for other possible causes.

Conditional requests

大多数响应都返回ETag标头。许多响应还返回Last-Modified标头。您可以使用这些标头的值分别使用If-None-Match和If-Modified-Since标头对这些资源进行后续请求。如果资源未更改，则服务器将返回304 Not Modified。

curl -i https://api.myblog.com/user
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Wed, 20 Nov 2019 15:31:30 GMT
Status: 200 OK
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset: 1372700873
curl -i https://api.myblog.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Wed, 20 Nov 2019 15:31:30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset: 1372700873
curl -i https://api.myblog.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
Last-Modified: Wed, 20 Nov 2019 15:31:30 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996
X-RateLimit-Reset: 1372700873

跨源资源共享

该API支持来自任何来源的AJAX请求的跨来源资源共享（CORS）。

curl -i https://api.myblog.com -H "Origin: http://example.com"
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

CORS之前的要求：

curl -i https://api.github.com -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

JSON-P回调
您可以将?callback参数发送到任何GET调用，以将结果包装在JSON函数中。当浏览器希望通过解决跨域问题将GitHub内容嵌入网页时，通常使用此方法。响应包括与常规API相同的数据输出，以及相关的HTTP标头信息。

curl https://api.github.com?callback=foo
/**/foo({
  "meta": {
    "status": 200,
    "X-RateLimit-Limit": "5000",
    "X-RateLimit-Remaining": "4966",
    "X-RateLimit-Reset": "1372700873",
    "Link": [ // pagination headers and other links
      ["https://api.github.com?page=2", {"rel": "next"}]
    ]
  },
  "data": {
    // the data
  }
})

时区

一些创建新数据的请求（例如创建新的提交）允许您在指定或生成时间戳时提供时区信息。我们按照优先级顺序应用以下规则，以确定API调用的时区信息。

明确提供带有时区信息的ISO 8601时间戳
使用Time-Zoneheader
使用用户的最后一个已知时区
默认为UTC，没有其他时区信息

明确提供带有时区信息的ISO 8601时间戳

对于允许指定时间戳的API调用，我们使用该确切的时间戳。例如Commits API。
这些时间戳看起来像2014-02-27T15:05:06+01:00。

使用Time-Zone header

可以Time-Zone根据Olson数据库中的名称列表提供定义时区的标头。

curl -H “Time-Zone: Europe/Amsterdam” -X POST https://api.myblog.com/repos/myblog/linguist/contents/new_file.md

这意味着我们将在此标头定义的时区中为您的API调用生成一个时间戳。例如，Contents API会为每次添加或更改生成一个git commit，并将当前时间用作时间戳。此标头将确定用于生成当前时间戳的时区。

使用用户的最后一个已知时区

如果未Time-Zone指定任何标头，并且您对API进行了身份验证的调用，那么我们将使用身份验证用户的最后一个已知时区。每当您浏览GitHub网站时，最新的时区就会更新。

默认为UTC，没有其他时区信息

如果以上步骤未产生任何信息，我们将UTC用作时区来创建git commit。

文章

查看用户所有文章

GET /:username/articles
curl -i -u https://api.myblog.com/v1/username/articles

查看用户特定文章

GET /:username/articles/details/{id}
curl -i -u https://api.myblog.com/v1/username/articles/details/id

查看文章评论

GET /:username/articles/details/{id}/comments
curl -i -u https://api.myblog.com/v1/username/articles/details/id/comments

创建评论

POST /:user/:id/comment
curl https://api.myblog.com/v1/username/articles/details/id/comments -d {“content”:“xxx”}

发布文章

POST /:user/articles
curl -d ‘{“title”:“xxx”,“content”:“xxx”,“private”:false,“description”:“xxx”}’ https://api.myblog.com/v1/username/articles

删除文章

DELETE /:user/articles/{id}

修改文章

PUT /:user/articles/{id}
curl -u -i -d {“title”:"",“content”:“xxx”} https://api.myblog.com/v1/username/articles

TempterCyn

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
服务计算--模仿github API用markdown编写设计一个博客网站的部分rest API

当前版本默认情况下，所有https://api.myblog.com接收v1 版本的REST API的请求。我们建议您通过Accept明确请求此版本。Accept: application/vnd.myblog.v1+json模式所有API访问都是通过HTTPS进行的，并且可以通过访问https://api.github.com。所有数据都以JSON的形式发送和接收。curl -i ...
复制链接

扫一扫