248 lines
5.8 KiB
Markdown
248 lines
5.8 KiB
Markdown
# INITIAL API
|
||
|
||
客户端初始化、基础数据和版本更新检查。
|
||
|
||
> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
|
||
|
||
## 接入方式
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/{Service}/{Method}`
|
||
- 原生 gRPC：`/initial.{Service}/{Method}`
|
||
- grpc-gateway：`POST /initial.{Service}/{Method}`
|
||
- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
|
||
- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
|
||
|
||
## 服务概览
|
||
|
||
| 服务 | 方法数 | 说明 |
|
||
|---|---:|---|
|
||
| `Check` | 3 | Check 服务 |
|
||
| `Data` | 3 | Data 服务 |
|
||
|
||
## Check
|
||
|
||
| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|
||
|---|---|---|---|---|
|
||
| `Hello` | `POST /rpc/initial/Check/Hello` | [`initial.Crc`](#initialcrc) | [`initial.StatusReply`](#initialstatusreply) | Unary |
|
||
| `Config` | `POST /rpc/initial/Check/Config` | [`initial.ConfigRequest`](#initialconfigrequest) | [`initial.ConfigReply`](#initialconfigreply) | Unary |
|
||
| `Updates` | `POST /rpc/initial/Check/Updates` | [`initial.CheckForUpdatesRequest`](#initialcheckforupdatesrequest) | [`initial.CheckForUpdatesReply`](#initialcheckforupdatesreply) | Unary |
|
||
|
||
### Check.Hello
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Check/Hello`
|
||
- gRPC：`/initial.Check/Hello`
|
||
- 白名单键：`initial.Check.Hello`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"code": "string"
|
||
}
|
||
```
|
||
|
||
### Check.Config
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Check/Config`
|
||
- gRPC：`/initial.Check/Config`
|
||
- 白名单键：`initial.Check.Config`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"app": "string",
|
||
"os": "string"
|
||
}
|
||
```
|
||
|
||
### Check.Updates
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Check/Updates`
|
||
- gRPC：`/initial.Check/Updates`
|
||
- 白名单键：`initial.Check.Updates`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"app": "string",
|
||
"arch": "string",
|
||
"os": "string",
|
||
"version": "string"
|
||
}
|
||
```
|
||
|
||
## Data
|
||
|
||
| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
|
||
|---|---|---|---|---|
|
||
| `Country` | `POST /rpc/initial/Data/Country` | [`initial.Empty`](#initialempty) | [`initial.CountryReply`](#initialcountryreply) | Unary |
|
||
| `Areas` | `POST /rpc/initial/Data/Areas` | [`initial.AreasRequest`](#initialareasrequest) | [`initial.AreasReply`](#initialareasreply) | Unary |
|
||
| `Datas` | `POST /rpc/initial/Data/Datas` | [`initial.Empty`](#initialempty) | [`initial.DatasReply`](#initialdatasreply) | Unary |
|
||
|
||
### Data.Country
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Data/Country`
|
||
- gRPC：`/initial.Data/Country`
|
||
- 白名单键：`initial.Data.Country`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
### Data.Areas
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Data/Areas`
|
||
- gRPC：`/initial.Data/Areas`
|
||
- 白名单键：`initial.Data.Areas`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{
|
||
"countryCode": "string",
|
||
"countryId": 0,
|
||
"showTown": false
|
||
}
|
||
```
|
||
|
||
### Data.Datas
|
||
|
||
- 动态 HTTP：`POST /rpc/initial/Data/Datas`
|
||
- gRPC：`/initial.Data/Datas`
|
||
- 白名单键：`initial.Data.Datas`
|
||
- 请求示例：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
## 消息结构
|
||
|
||
### initial.AreasItem
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `id` | `string` | 可选 |
|
||
| `pid` | `string` | 可选 |
|
||
| `deep` | `int32` | 可选 |
|
||
| `name` | `string` | 可选 |
|
||
| `pinyinPrefix` | `string` | 可选 |
|
||
| `pinyin` | `string` | 可选 |
|
||
| `extId` | `string` | 可选 |
|
||
| `extName` | `string` | 可选 |
|
||
|
||
### initial.AreasReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `areas` | `[]initial.AreasItem` | 数组 |
|
||
|
||
### initial.AreasRequest
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `countryId` | `int32` | 可选 |
|
||
| `countryCode` | `string` | 可选 |
|
||
| `showTown` | `bool` | 可选 |
|
||
|
||
### initial.CheckForUpdatesReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `identity` | `string` | 可选 |
|
||
| `version` | `string` | 可选 |
|
||
| `summary` | `string` | 可选 |
|
||
| `files` | `string` | 可选 |
|
||
| `pubdate` | `string` | 可选 |
|
||
|
||
### initial.CheckForUpdatesRequest
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `app` | `string` | 可选 |
|
||
| `os` | `string` | 可选 |
|
||
| `arch` | `string` | 可选 |
|
||
| `version` | `string` | 可选 |
|
||
|
||
### initial.ConfigItem
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `Identity` | `string` | 可选 |
|
||
| `key` | `string` | 可选 |
|
||
| `value` | `string` | 可选 |
|
||
| `version` | `int64` | 可选 |
|
||
|
||
### initial.ConfigReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `data` | `[]initial.ConfigItem` | 数组 |
|
||
|
||
### initial.ConfigRequest
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `app` | `string` | 可选 |
|
||
| `os` | `string` | 可选 |
|
||
|
||
### initial.CountryItem
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `id` | `uint32` | 可选 |
|
||
| `Iso2` | `string` | 可选 |
|
||
| `Iso3` | `string` | 可选 |
|
||
| `numCode` | `string` | 可选 |
|
||
| `phoneCode` | `string` | 可选 |
|
||
| `currency` | `string` | 可选 |
|
||
| `currencySymbol` | `string` | 可选 |
|
||
| `region` | `string` | 可选 |
|
||
| `timezones` | `string` | 可选 |
|
||
| `translations` | `string` | 可选 |
|
||
| `name` | `string` | 可选 |
|
||
| `localName` | `string` | 可选 |
|
||
| `enabled` | `bool` | 可选 |
|
||
| `sortOrder` | `int32` | 可选 |
|
||
|
||
### initial.CountryReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `countries` | `[]initial.CountryItem` | 数组 |
|
||
|
||
### initial.Crc
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `code` | `string` | 可选 |
|
||
|
||
### initial.DatasItem
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `id` | `int64` | 可选 |
|
||
| `dataType` | `string` | 可选 |
|
||
| `key` | `string` | 可选 |
|
||
| `title` | `string` | 可选 |
|
||
| `remark` | `string` | 可选 |
|
||
| `icon` | `string` | 可选 |
|
||
|
||
### initial.DatasReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `datas` | `[]initial.DatasItem` | 数组 |
|
||
|
||
### initial.Empty
|
||
|
||
空消息：请求时发送 `{}`。
|
||
|
||
### initial.StatusReply
|
||
|
||
| JSON 字段 | 类型 | 规则 |
|
||
|---|---|---|
|
||
| `code` | `int32` | 可选 |
|
||
| `message` | `string` | 可选 |
|
||
| `details` | `string` | 可选 |
|
||
| `timeseq` | `int64` | 可选 |
|