This repository has been archived on 2024-04-14. You can view files and clone it, but cannot push or open issues or pull requests.
icydns/README.md

218 lines
4.0 KiB
Markdown
Raw Normal View History

2021-05-16 09:55:56 +00:00
# IcyDNS HTTP API
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
HTTP API for managing BIND zone files.
## Running
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
This application is intended to be run behind a proxy. Requires node v14+ for `fs/promises`. Also requires `bind-tools` for checking zone files.
2021-05-21 13:41:06 +00:00
- `npm install`
- `npm run build`
- `npm start`
2021-05-16 09:55:56 +00:00
### Environment variables
2021-05-21 13:41:06 +00:00
- `PORT` - server port
- `ZONEFILES` - path to zone files
- `CACHE_TTL` - internal zone cache time-to-live
2021-07-08 10:57:20 +00:00
- `LOG_DIR` - Logs directory
- `LOG_FILES` - Log to files (boolean)
2021-05-21 13:41:06 +00:00
- `RNDC_SERVER` - RNDC host
- `RNDC_PORT` - RNDC port
- `RNDC_KEYFILE` - location of RNDC's key file
2021-05-16 09:55:56 +00:00
Zones are automatically reloaded using `rndc` after updates. If you do not have rndc configured, you will need to reload the zones manually, but the files still get updated.
## API
**All requests are prefixed with `/api/v1`.** Authorization is by bearer token, i.e. `-H 'Authorization: Bearer <token>'`. `?` denotes optional parameter.
2021-05-21 13:41:06 +00:00
### `GET /zone/{domain}`
Returns all of `{domain}`'s DNS records.
2021-05-16 09:55:56 +00:00
**Query:** None
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
ttl: number;
records: [
[index]: {
name: string;
type: string;
value: string;
}
]
}
```
2021-05-21 13:41:06 +00:00
### `GET /zone/{domain}/download`
Provides `{domain}`'s records as a file.
2021-05-16 09:55:56 +00:00
**Query:** None
**Response:** BIND zone file
2021-05-21 13:41:06 +00:00
### `POST /zone/{domain}`
Reloads `{domain}`'s zone file. Optionally changes the zone file's TTL value.
2021-05-16 09:55:56 +00:00
**Body:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
ttl?: number;
}
```
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
success: boolean;
message: string;
ttl?: number;
}
```
2021-05-21 13:41:06 +00:00
### `GET /zone/records/{domain}`
Returns all of `{domain}`'s DNS records or performs a search based on provided query parameters.
2021-05-16 09:55:56 +00:00
**Query:**
2021-05-21 13:41:06 +00:00
- `name?`
- `type?`
- `value?`
2021-05-16 09:55:56 +00:00
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
[
[index]: {
name: string;
type: string;
value: string;
index?: number; // when searching only
}
]
```
2021-05-21 13:41:06 +00:00
### `PATCH /zone/records/{domain}`
Updates or marks for deletion a single or multiple DNS records of `{domain}` at `index`. **Warning:** `setIndex` will cause your other records to shift around, so it is currently only recommended to use for a single record at a time.
2021-05-16 09:55:56 +00:00
**Body:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
record: {
index: number;
2021-05-16 09:55:56 +00:00
name?: string;
type?: string;
value?: string;
2021-05-16 16:18:07 +00:00
setIndex?: number;
2021-05-16 14:40:48 +00:00
forDeletion?: boolean;
} | {...}[];
2021-05-16 09:55:56 +00:00
}
```
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
success: boolean;
message: string;
changed: DNSRecord[];
errors: {
message: string;
record: DNSRecord;
}[];
2021-05-16 09:55:56 +00:00
}
```
2021-05-21 13:41:06 +00:00
### `POST /zone/records/{domain}`
Creates a single or multiple new DNS records for `{domain}`.
2021-05-16 09:55:56 +00:00
**Body:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
record: {
name: string;
type: string;
value: string;
2021-05-16 16:18:07 +00:00
index?: number; // insert at this exact index (not after this index, at it!)
} | {...}[];
2021-05-16 09:55:56 +00:00
}
```
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
success: boolean;
message: string;
created: ({ index: number, ...DNSRecord })[];
errors: {
message: string;
record: DNSRecord;
}[];
2021-05-16 09:55:56 +00:00
}
```
2021-05-21 13:41:06 +00:00
### `DELETE /zone/records/{domain}`
Deletes a single or multiple DNS records from `{domain}` at `index`. **Warning:** Deleting an index that is not at the end of the record causes following records' indexes to shift back by one. Refresh your indexes after every addition and deletion!
2021-05-16 09:55:56 +00:00
**Body:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
2021-05-16 14:40:48 +00:00
index: number | number[];
2021-05-16 09:55:56 +00:00
}
```
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
success: boolean;
message: string;
2021-05-16 14:40:48 +00:00
deleted: DNSRecord[];
errors: {
message: string;
record: DNSRecord;
}[];
2021-05-16 09:55:56 +00:00
}
```
2021-05-21 13:41:06 +00:00
### `POST /set-ip/{domain}`
Quickly updates the `{domain}`'s IP address (first occurences of `A` and `AAAA` records of `@` or `subdomain`). One of the IP addresses is taken from the request, so it's a good idea to use curl with `-4` to automatically set the IPv4 address and provide the IPv6 address with a body parameter.
2021-05-16 09:55:56 +00:00
**Body:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
ipv4?: string;
ipv6?: string;
subdomain?: string;
dualRequest?: boolean;
}
```
**Response:**
2021-05-21 13:41:06 +00:00
2021-05-16 09:55:56 +00:00
```typescript
{
success: boolean;
message: string;
actions: string[]; // detailed descriptions of what was actually done
}
```