myblog的restful API设计文档（markdown格式）

当前版本

默认情况下，所有到https://api.myblog.com的请求都会收到REST API的v3版本。我们建议您通过Accept 显式地请求这个版本。

Accept: application/vnd.myblog.v3+json

版本历史

日期	版本号	作者	备注
2019.11.17	1.0	Ailsa	新版本发布
2019.11.18	1.1	Ailsa	新版本发布

文档介绍

本文档的接口遵循RESTful设计风格。

登录认证流程

基于JWT认证机制，实现登录认证流程。

模式

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

curl -i https://api.myblog.com/users/octocat/orgs
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-myblog-Media-Type: myblog.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

接口返回一共有三种情况：

1. 操作成功后返回，范例：

{
   
  "code": "200",
  "msg": "SUCCESS"
} 

1. 成功返回数据，范例：

{
   
  "data": {
   
    "name": "minhow",
    "age": "18"
  },
  "code": "200",
  "msg": "SUCCESS"
}

1. 错误返回，范例：

{
   
  "err_code": "1001",
  "err_msg": "wrong,again！"
}

身份验证

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

基本认证

curl -u "username" https://api.myblog.com

Token 验证

Token访问有效期为两个小时，刷新有效期为两周。

刷新Token值

请求说明

请求方式：PATCH
返回结果：

{
   
  "data": {
   
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vdm95YWdlLmRldi9hdXRob3JpemF0aW9ucy9yZWZyZXNoLXRva2VucyIsImlhdCI6MTQ4OTk4Nzg0OCwiZXhwIjoxNDg5OTg3OTc3LCJuYmYiOjE0ODk5ODc5MTcsImp0aSI6IlRvNmxzamhwTTNpcmhRQlAiLCJ1dWlkIjoiNWZlYzI0NzAifQ.hgZsQq5rT5VXAwUilEv5P1JIhLrctJPKAkKWBSqwu3c"
  },
  "code": "200",
  "msg": "SUCCESS"
}

返回参数

字段	字段类型	字段说明
token	string	token值

登录

请求说明

请求方式：POST

请求URL: login

请求参数：

字段	字段类型	字段说明
email	string	邮箱
username	string	账户
password	string	密码

返回结果：

{
   
  "data": {
   
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
  },
  "code": "200",
  "msg": "SUCCESS"
}

登录限制失败

使用无效凭据进行身份验证将返回401>未经授权：

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

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

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/v3"
}

参数

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

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

在本例中，为路径中的:owner和:repo参数提供了’vmg’和’redcarpet’值，而:state则在查询字符串中传递。

对于POST、PATCH、PUT和DELETE请求，URL中没有包含的参数应该用“application/ JSON”的内容类型编码为JSON:

curl -i -u username -d '{"scopes":["public_repo"]}' https://api.myblog.com/authorizations

客户端错误

在接收请求体的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. Sending invalid fields will result in a422 Unprocessable Entity response.```

   HTTP/1.1