文档目录

HTTP API 结构

HTTP API 接口为开发者提供管理 坦克NS 记录的外部接口，这些接口通信使用json格式，通过构建正确的请求便可以达到管理目标。这些接口包括修改记录、修改Zone记录、获取记录、获取Zone记录、删除记录、删除Zone和删除Zone记录。下面我将会一条一条描述这些记录的结构。

基础

认识结构体前，先描述一下基础知识。json 结构的根包含4个顶级字段：分别是 Header、Query、Error 和 Answer。Header 和 Query 在请求的时候必须设置。Error 和Answer 则不同，出现错误的时候，响应的时候 Error 才会设置。如果成功，则不会返回 Error 字段，只返回 Header 和 Answer。

请求地址：http://服务器:9100/api/v1/ 端口默认是 9100 。如果使用随机端口，应该查看软件运行输出日志。

字段 意义
Token token 用于替代密码用于会话认证
Language 指定处理程序使用的语言来响应，目前只支持 1
Query Count 请求数量，只支持 1
Error Count 错误数量，一般是 1
Answer Count 回答数量，一般是 1

Query

字段 意义
Type 操作类型，指定请求的操作是什么。
Params 参数，传输给后端的参数，根据不同 Type ，参数不同。
Format Desired 通信文档格式，目前只支持 Json

Query.Type

值 意义
1 获取 token
2 获取用户登陆状态
3 登陆
4 登出
5 修改 RR
6 修改 Zone RR
7 删除 RR
8 删除 Zone
9 删除 Zone RR
10 获取所有 RR
11 获取所有 Zone

Query.Params

值 意义
User 用户对象，登陆的时候需要设置。
RRs 记录集，添加或修改记录时需要设置。
Zones Zone集，添加或修改zone记录时需要设置。
User
值 意义
Name 用户名
Password 密码
RR（Query.Params.RR | Answer.Data.RR）
字段 意义
Id 记录id
Name 记录名
Value 记录值
Type 记录类型
Ttl 记录生存时间
Preference 记录优先级
Zone（Query.Params.Zone | Answer.Data.Zone ）
字段 意义
Name zone名称
RRs 记录集，与 Data.RR 一致

Error

字段 意义
Type 类型
Error Code 错误代码
Message 字符串消息

Answer

字段 意义
Type 操作类型，与请求的一样
Format 格式，目前只支持 json
Data 数据包括一个 Data 对象。
Answer Code 代码，成功返回 200

Answer.Data

字段 意义
Message 描述性消息
IsLoggedIn 用户是否登陆
RRs 记录集 是一个 RR 数组
Zones Zone集 是一个 Zone 数组

会话

获取TOKEN

请求

Params 空。

{
    "header": {
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 1,
        "format_desired": "json",
        "params": {}
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 1,
        "format": "json",
        "code": 200,
        "data": {
            "message": "获取token成功"
        }
    }
}

获取用户登陆状态

请求

Params 空。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 2,
        "format_desired": "json",
        "params": {}
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 2,
        "format": "json",
        "code": 200,
        "data": {
            "message": "已经登出",
            "is_logged_in": false
        }
    }
}

登陆

请求

Params 为 user 对象。user 对象包括 name, password。就是用户名和密码。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 3,
        "format_desired": "json",
        "params": {
            "user": {
                "name": "tankns",
                "password": "123456"
            }
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 3,
        "format": "json",
        "code": 200,
        "data": {
            "message": "登陆成功"
        }
    }
}

登出

请求

Params 空。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 4,
        "format_desired": "json",
        "params": {}
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 4,
        "format": "json",
        "code": 200,
        "data": {
            "message": "登出成功"
        }
    }
}




记录

修改记录

Params 是 rrs 对象，rrs 对象包括：id，name，value，type，ttl。 增加记录与修改记录使用的是同一个API。如果是新增，id必须是0。如果是更新，id是要更新记录的 id。

请求

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 5,
        "format_desired": "json",
        "params": {
            "rrs": [
                {
                    "id": 0,
                    "name": "www.ganyaotong.org.com",
                    "value": "127.0.0.12",
                    "type": "a",
                    "ttl": "660"
                }
            ]
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 5,
        "format": "json",
        "code": 200,
        "data": {
            "message": "添加记录成功"
        }
    }
}

获取记录

请求

Params 空。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 10,
        "format_desired": "json",
        "params": {}
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 10,
        "format": "json",
        "code": 200,
        "data": {
            "message": "获取RRs成功",
            "rrs": [
                {
                    "id": 2,
                    "name": "www.ganyaotong.org.com",
                    "value": "127.0.0.12",
                    "type": "A",
                    "ttl": "660"
                }
            ]
        }
    }
}

删除记录

请求

Params 为 rrs。rrs 包括要删除的 id 对象的数组。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 7,
        "format_desired": "json",
        "params": {
            "rrs": [
                {
                    "id": 2
                }
            ]
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 7,
        "format": "json",
        "code": 200,
        "data": {
            "message": "删除记录成功"
        }
    }
}




Zone

修改Zone记录

请求

Params 为 zones 。 zones 包括 name 和 rrs。rrs 就是 id, name， value，type，ttl。 增加 Zone 记录与修改 Zone 记录使用的是同一个API。如果是新增，id必须是0。如果是更新，id是要更新记录的 id。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 6,
        "format_desired": "json",
        "params": {
            "zones": [
                {
                    "name": "tk",
                    "rrs": [
                        {
                            "id": 0,
                            "name": "www.ctr-444888",
                            "value": "192.168.2.210",
                            "type": "a",
                            "ttl": "660"
                        }
                    ]
                }
            ]
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 6,
        "format": "json",
        "code": 200,
        "data": {
            "message": "添加记录成功"
        }
    }
}

获取Zone记录

请求

Params 空。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 11,
        "format_desired": "json",
        "params": {}
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 11,
        "format": "json",
        "code": 200,
        "data": {
            "message": "获取Zones成功",
            "zones": [
                {
                    "name": "tk",
                    "rrs": [
                        {
                            "id": 1,
                            "name": "www.ctr-444888",
                            "value": "192.168.2.210",
                            "type": "A",
                            "ttl": "660"
                        }
                    ]
                }
            ]
        }
    }
}

删除Zone

请求

Params 为 zones。zones 包括 name，是需要删除的 zone 的名。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 8,
        "format_desired": "json",
        "params": {
            "zones": [
                {
                    "name": "tk"
                }
            ]
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 8,
        "format": "json",
        "code": 200,
        "data": {
            "message": "删除Zone成功"
        }
    }
}

删除Zone记录

请求

Params 为 zones。zones 包括 name 和 rrs，rrs 包括 id 对象的数组。

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "query_count": 1
    },
    "query": {
        "type": 9,
        "format_desired": "json",
        "params": {
            "zones": [
                {
                    "name": "tk",
                    "rrs": [
                        {
                            "id": 1
                        }
                    ]
                }
            ]
        }
    }
}

响应

{
    "header": {
        "token_id": "tpYyggfo3z0uxZIWTGy94pnPhF6PRKkU2gJaO5sdWHVGbAH7",
        "language_id": 1,
        "answer_count": 1
    },
    "query": {},
    "answer": {
        "type": 9,
        "format": "json",
        "code": 200,
        "data": {
            "message": "删除Zone的记录成功"
        }
    }
}