203 lines
5.1 KiB
Markdown
203 lines
5.1 KiB
Markdown
# Bird-lg-go API documentation
|
|
|
|
The frontend provides an API for running BIRD/traceroute/whois queries.
|
|
|
|
API Endpoint: `https://your.frontend.com/api/` (the last slash must not be omitted!)
|
|
|
|
Requests are sent as POSTS with JSON bodies.
|
|
|
|
## Table of Contents
|
|
|
|
* [Bird-lg-go API documentation](#bird-lg-go-api-documentation)
|
|
* [Table of Contents](#table-of-contents)
|
|
* [Request fields](#request-fields)
|
|
* [Example request of type bird](#example-request-of-type-bird)
|
|
* [Example request of type server_list](#example-request-of-type-server_list)
|
|
* [Response fields (when type is summary)](#response-fields-when-type-is-summary)
|
|
* [Fields for apiSummaryResultPair](#fields-for-apisummaryresultpair)
|
|
* [Fields for SummaryRowData](#fields-for-summaryrowdata)
|
|
* [Example response](#example-response)
|
|
* [Response fields (when type is bird, traceroute, whois or server_list)](#response-fields-when-type-is-bird-traceroute-whois-or-server_list)
|
|
* [Fields for apiGenericResultPair](#fields-for-apigenericresultpair)
|
|
* [Example response of type bird](#example-response-of-type-bird)
|
|
* [Example response of type server_list](#example-response-of-type-server_list)
|
|
|
|
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
|
|
|
|
## Request fields
|
|
|
|
| Name | Type | Value |
|
|
| ---- | ---- | -------- |
|
|
| `servers` | array of `string` | List of servers to be queried |
|
|
| `type` | `string` | Can be `summary`, `bird`, `traceroute`, `whois` or `server_list` |
|
|
| `args` | `string` | Arguments to be passed, see below |
|
|
|
|
Argument examples for each type:
|
|
|
|
- `summary`: `args` is ignored. Recommended to set to empty string.
|
|
- `bird`: `args` is the command to be passed to bird, e.g. `show route for 8.8.8.8`
|
|
- `traceroute`: `args` is the traceroute target, e.g. `8.8.8.8` or `google.com`
|
|
- `whois`: `args` is the whois target, e.g. `8.8.8.8` or `google.com`
|
|
- `server_list`: `args` is ignored. In addition, `servers` is also ignored.
|
|
|
|
### Example request of type `bird`
|
|
|
|
```json
|
|
{
|
|
"servers": [
|
|
"alpha"
|
|
],
|
|
"type": "bird",
|
|
"args": "show route for 8.8.8.8"
|
|
}
|
|
```
|
|
|
|
### Example request of type `server_list`
|
|
|
|
```json
|
|
{
|
|
"servers": [],
|
|
"type": "server_list",
|
|
"args": ""
|
|
}
|
|
```
|
|
|
|
## Response fields (when `type` is `summary`)
|
|
|
|
| Name | Type | Value |
|
|
| ---- | ---- | -------- |
|
|
| `error` | `string` | Error message when something is wrong. Empty when everything is good |
|
|
| `result` | array of `apiSummaryResultPair` | See below |
|
|
|
|
### Fields for `apiSummaryResultPair`
|
|
|
|
| Name | Type | Value |
|
|
| ---- | ---- | -------- |
|
|
| `server` | `string` | Name of the server |
|
|
| `data` | array of `SummaryRowData` | Summaries of the server, see below |
|
|
|
|
### Fields for `SummaryRowData`
|
|
|
|
All fields below is 1:1 correspondent to the output of `birdc show protocols`.
|
|
|
|
| Name | Type |
|
|
| ---- | ---- |
|
|
| `name` | `string` |
|
|
| `proto` | `string` |
|
|
| `table` | `string` |
|
|
| `state` | `string` |
|
|
| `since` | `string` |
|
|
| `info` | `string` |
|
|
|
|
### Example response
|
|
|
|
Request:
|
|
```json
|
|
{
|
|
"servers": [
|
|
"alpha"
|
|
],
|
|
"type": "summary",
|
|
"args": ""
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"error": "",
|
|
"result": [
|
|
{
|
|
"server": "alpha",
|
|
"data": [
|
|
{
|
|
"name": "bgp1",
|
|
"proto": "BGP",
|
|
"table": "---",
|
|
"state": "start",
|
|
"since": "2021-01-15 22:40:01",
|
|
"info": "Active Socket: Operation timed out"
|
|
},
|
|
{
|
|
"name": "bgp2",
|
|
"proto": "BGP",
|
|
"table": "---",
|
|
"state": "start",
|
|
"since": "2021-01-03 08:15:48",
|
|
"info": "Established"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Response fields (when `type` is `bird`, `traceroute`, `whois` or `server_list`)
|
|
|
|
| Name | Type | Value |
|
|
| ---- | ---- | -------- |
|
|
| `error` | `string` | Error message, empty when everything is good |
|
|
| `result` | array of `apiGenericResultPair` | See below |
|
|
|
|
### Fields for `apiGenericResultPair`
|
|
|
|
| Name | Type | Value |
|
|
| ---- | ---- | -------- |
|
|
| `server` | `string` | Name of the server; is empty when type is `whois` |
|
|
| `data` | `string` | Result from the server; is empty when type is `server_list` |
|
|
|
|
### Example response of type `bird`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"servers": [],
|
|
"type": "server_list",
|
|
"args": ""
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"error": "",
|
|
"result": [
|
|
{
|
|
"server": "alpha",
|
|
"data": "BIRD v2.0.7-137-g61dae32b\nRouter ID is 1.2.3.4\nCurrent server time is 2021-01-17 04:21:14.792\nLast reboot on 2021-01-03 08:15:48.494\nLast reconfiguration on 2021-01-17 00:49:10.573\nDaemon is up and running\n"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Example response of type `server_list`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"servers": [
|
|
"alpha"
|
|
],
|
|
"type": "bird",
|
|
"args": "show status"
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"error": "",
|
|
"result": [
|
|
{
|
|
"server": "gigsgigscloud",
|
|
"data": ""
|
|
}
|
|
]
|
|
}
|
|
```
|