init getting-developed

docs/getting-developed/_category_.json

@@ -0,0 +1,11 @@
+{
+  "position": 1,
+  "label": "准备开发",
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Getting Developed",
+    "slug": "/getting-developed"
+  }
+}

docs/getting-developed/access-token-and-signature.md

@@ -0,0 +1,145 @@
+---
+title: API 访问凭证与签名
+id: access-token-and-signature
+slug: /access-token-and-signature
+---
+
+### 签名流程
+  - 创建请求请求描述
+  - 使用请求描述和额外的元数据生成签名字符串
+  - 使用 api secret key 对字符串进行签名
+  - 把签名放到请求头中
+
+### 例子
+```
+POST https://openapi.lbkrs.com/example/first\ and\ second?action=test&size=123 HTTP/1.1
+Host openapi.lbkrs.com
+Content-Type application/json
+X-Timestamp 1639021402940.728
+X-Api-Key {这里是 access key} 
+Authorization {这里是 token}
+{"foo":"bar"}
+
+```
+
+### 创建请求描述
+伪代码
+```
+CanonicalRequest =
+  HTTPRequestMethod + '|' +
+  CanonicalURI + '|' +
+  CanonicalQueryString + '|' +
+  CanonicalHeaders + '|' +
+  SignedHeaders + '|' +
+  HexEncode(Hash(RequestPayload))
+```
+
+
+#### HttpRequest Method
+POST
+#### CanonicalURI
+/example/first\ and\ second
+
+#### CanonicalQueryString
+action=test&size=123
+
+#### CanonicalHeaders
+```
+CanonicalHeaders =
+CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ... + CanonicalHeadersEntryN
+CanonicalHeadersEntry =
+Lowercase(HeaderName) + ':' + TrimSpace(HeaderValue) + '\n'
+```
+
+这里和 aws signature v4 不同，这里我们只使用固定的几个 headers。请求会经过中间层，比如 cdn 可能会在请求头上添加一些其他内容
+```
+- authorization
+- x-api-key
+- x-timestamp
+```
+---
+**NOTE**
+顺序由 SignedHeaders 决定
+---
+CanonicalHeaders 例子：
+```
+x-api-key:xxx\n
+x-timestamp:1639021402940.728\n
+Authorization {这里是 token}
+```
+
+#### SignedHeaders
+用来加签的请求头，同样需要按字母表排序
+```
+SignedHeaders =
+Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... + Lowercase(HeaderNameN)
+```
+SignedHeaders 例子:
+```
+x-api-key;x-timestamp;authorization
+```
+
+HexEncode(Hash(payload))
+Hash 使用 sha1 
+```
+// HexEncode(Hash(`{"foo":"bar"}`))
+a5e744d0164540d33b1d7ea616c28f2fa97e754a
+```
+
+---
+**NOTE**
+当 Payload 不为空时需要 hash。并且 Hash 都用小写的 16 进制
+---
+
+#### 请求描述
+我们将前面生成的例子结果合并起来就是
+```
+GET|/example/first and second|action=test&size=123|x-api-key:xxx
+x-timestamp:1639021402940.728
+|x-api-key;x-timestamp|a5e744d0164540d33b1d7ea616c28f2fa97e754a
+
+```
+
+
+### 创建加签字符串
+StringToSign = Algorithm|HashedCanonicalRequest
+
+支持的加签名算法
+- HMAC-MD5
+- HMAC-SHA1
+- HMAC-SHA256
+
+例子中我们使用 HMAC-SHA256，那么 Algorithm 就是 HMAC-SHA256
+
+我们对请求描述进行 SHA1 hash，得到：
+`0e3de7dd1fd206284395484504660272f91d24cc`
+
+加签字符串为 
+```
+HMAC-SHA256|0e3de7dd1fd206284395484504660272f91d24cc
+```
+
+### 使用 api secret key 对字符串进行签名
+
+这里使用的 secret 为 `1c1ca804eb3f2ac9f13d88da958e73a8d3ead1450f8ca2707a834709b1382e2d`
+
+```
+HMAC(HMAC-SHA256|0e3de7dd1fd206284395484504660272f91d24cc, 1c1ca804eb3f2ac9f13d88da958e73a8d3ead1450f8ca2707a834709b1382e2d)
+```
+
+结果为
+`e8ae6b1d962d4e3218fa605d6fdd23107a94a985d62f8ab2903091098e9b09f6``
+
+
+请求中添加签名
+格式
+```
+X-Api-Signature: $algorithm SignedHeaders=$SignedHeaders, Signature=$Signature
+```
+
+例子的结果为：
+```
+X-Api-Signature: HMAC-SHA256 SignedHeaders=x-api-key;x-timestamp, Signature=091751bfa20a96f0441698c0d040bf8a6c43f15874e48e489b3e098f354422a9
+```
+
+

docs/getting-developed/general-error-code.md

@@ -0,0 +1,17 @@
+---
+title: 通用错误码 
+id: general-error-code 
+slug: /general-error-code
+---
+
+### 错误码
+
+| http 状态码 | 错误 code | 错误信息 | 说明 |
+|---|---|---|---|
+| 403 | 403201 | signature invalid | 签名错误 |
+| 403 | 403202 | duplicae request | 重复请求，同一个请求没有更换 x-timestamp |
+| 403 | 403203 | apikey illegal | Apikey 非法 |
+| 401 | 401003 | Token过期 | Token 过期。可以通过 refresh token 刷新 |
+| 401 | 401004 | 缺少 token 信息|||
+| 429 | 429001 | IP 限流 |||
+| 429 | 429303 | 网关自身熔断 |||

docs/getting-developed/how-to-access-api.md

@@ -0,0 +1,60 @@
+---
+title: 如何调用服务端 API 
+id: how-to-access-api 
+slug: /how-to-access-api
+---
+
+## API 调用流程
+
+下图是 API 调用流程： 
+
+![how to access api flow](../../static/how-to-access-api-flow.png)
+
+### 1. 获取 Access Key 
+
+首先要申请 Access Key 拿到 Access Secret， 并设置相应权限。获取 Access Key 与申请权限请参考 [链接]。
+
+### 2. 创建 Token 
+
+在开发者后台中创建 Token。详见【链接】。
+
+### 3. 生成签名 
+
+先根据相应的 API 文档构造请求后， 通过 openapi sdk【链接】直接调用 API，sdk 会帮助生成签名， 或者根据授权与签名文档中的算法自己生成签名, 并设置相应的请求参数。
+
+### 4. 调用 API 
+
+使用 http 客户端发送签名过后的请求。
+
+## API 调用方式
+
+调用服务端接口需要是用 HTTPS 协议，JSON 格式，并是用 UTF-8 编码。
+
+示例如下：
+
+```bash
+curl -v http://127.0.0.1:8080/v1/test -H "X-Api-Signature: {签名}" -H "X-Api-Key: {access key}" -H "authorization: {token}" -H "X-Timestamp: {签名时间}"
+```
+
+## API 响应结果说明
+
+所有 API 相应体结构都包括 code, message, data 三个部分。code 是业务码，message 是错误信息，data 是请求结果。
+请求成功时 code 为 0，http status 为 200，当请求失败时 code 不为 0，并且 http status 不为 200。
+
+例如：
+```
+http code: 200
+http body: {
+  "code": 0,
+  "msg": "success"
+}
+
+```
+```
+http code: 403 
+http body: {
+  "code": 403201,
+  "msg": "signature invalid"
+}
+```
+