icydns/README.md

# IcyDNS HTTP API
HTTP API for managing BIND zone files.

## Running
This application is intended to be run behind a proxy. Requires node v14+ for `fs/promises`. Also requires `bind-tools` for checking zone files.

* `npm install`
* `npm run build`
* `npm start`

### Environment variables
* `PORT` - server port
* `ZONEFILES` - path to zone files
* `CACHE_TTL` - internal zone cache time-to-live
* `RNDC_SERVER` - RNDC host
* `RNDC_PORT` - RNDC port
* `RNDC_KEYFILE` - location of RNDC's key file

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.

### `GET /zone/:domain`
Returns all of `:domain`'s DNS records.

**Query:** None

**Response:**
```typescript
{
  ttl: number;
  records: [
    [index]: {
      name: string;
      type: string;
      value: string;
    }
  ]
}
```

### `GET /zone/:domain/download`
Provides `:domain`'s records as a file.

**Query:** None

**Response:** BIND zone file

### `POST /zone/:domain`
Reloads `:domain`'s zone file. Optionally changes the zone file's TTL value.

**Body:**
```typescript
{
  ttl?: number;
}
```

**Response:**
```typescript
{
  success: boolean;
  message: string;
  ttl?: number;
}
```

### `GET /zone/records/:domain`
Returns all of `:domain`'s DNS records or performs a search based on provided query parameters.

**Query:**
* `name?`
* `type?`
* `value?`

**Response:**
```typescript
[
  [index]: {
    name: string;
    type: string;
    value: string;
    index?: number; // when searching only
  }
]
```

### `POST /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.

**Body:**
```typescript
{
  record: {
    index: number;
    name?: string;
    type?: string;
    value?: string;
    setIndex?: number;
    forDeletion?: boolean;
  } | {...}[];
}
```

**Response:**
```typescript
{
  success: boolean;
  message: string;
  changed: DNSRecord[];
  errors: {
    message: string;
    record: DNSRecord;
  }[];
}
```

### `PUT /zone/records/:domain`
Creates a single or multiple new DNS records for `:domain`.

**Body:**
```typescript
{
  record: {
    name: string;
    type: string;
    value: string;
    index?: number; // insert at this exact index (not after this index, at it!)
  } | {...}[];
}
```

**Response:**
```typescript
{
  success: boolean;
  message: string;
  created: ({ index: number, ...DNSRecord })[];
  errors: {
    message: string;
    record: DNSRecord;
  }[];
}
```

### `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!

**Body:**
```typescript
{
  index: number | number[];
}
```

**Response:**
```typescript
{
  success: boolean;
  message: string;
  deleted: DNSRecord[];
  errors: {
    message: string;
    record: DNSRecord;
  }[];
}
```

### `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.

**Body:**
```typescript
{
  ipv4?: string;
  ipv6?: string;
  subdomain?: string;
  dualRequest?: boolean;
}
```

**Response:**
```typescript
{
  success: boolean;
  message: string;
  actions: string[]; // detailed descriptions of what was actually done
}
```