API

LuaDNS allows you to edit your zones and records through a simple REST API. The API can be accessed only through HTTPS and all requests must be authenticated. The authentication method used by the API is standard HTTP Basic Authentication. The server accepts and sends data in JSON format only, all requests should set the Accept header to application/json.

URL

Current version of the API is v1, the API URL is:

https://api.luadns.com/v1

Authentication

To use HTTP Basic Authentication you'll need a username (your email) and a password (API_Token), you can find your API_Token in the settings page.

Server error codes

The server will return HTTP 200 status code on successful operations, on errors returns:

HTTP/1.1 <StatusCode>
...
{
  "status": "<StatusMessage>",
  "request_id": "<RequestID>",
  "message": "<UserMessage>"
}

Status codes:

  • 400 - Bad Request (malformed request)
  • 422 - Unprocesable Entity (validation error)
  • 401 - Unauthorized (authentication failed)
  • 403 - Forbidden (operation not allowed)
  • 404 - Not Found (resource not found)
  • 500 - Internal Server Error (should be retried later)

Zones

This endpoint allows you to list/add/get/delete your hosted zones.

List zones

List all your hosted zones:

GET /zones

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones

The server returns an array with all account zones:

[
  {
    "id": 1,
    "name": "example.com",
    "synced": false,
    "queries_count": 0,
    "records_count": 3,
    "aliases_count": 0,
    "redirects_count": 0,
    "forwards_count": 0,
    "template_id": 0
  },
  {
    "id": 2,
    "name": "example.net",
    "synced": false,
    "queries_count": 0,
    "records_count": 3,
    "aliases_count": 0,
    "redirects_count": 0,
    "forwards_count": 0,
    "template_id": 0
  }
]

Create a zone

To create a new zone, submit your JSON encoded data using POST request:

POST /zones

Parameters:

  • name - Domain name (string, required)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        -X POST \
        -d '<json>' \
        https://api.luadns.com/v1/zones

On successful request the server returns the new zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 0,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0
}

Get a zone

To retrieve a zone by :id use:

GET /zone/:id

Parameters:

  • :id - Zone ID (integer)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/3

The server returns the zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 3,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0,
  "records": [
    {
      "id": 6683,
      "name": "example.org.",
      "type": "SOA",
      "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421501178 1200 120 604800 3600",
      "ttl": 3600,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.52747Z",
      "updated_at": "2015-01-17T13:26:17.527471Z"
    },
    {
      "id": 6684,
      "name": "example.org.",
      "type": "NS",
      "content": "a.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.529741Z",
      "updated_at": "2015-01-17T13:26:17.529741Z"
    },
    {
      "id": 6685,
      "name": "example.org.",
      "type": "NS",
      "content": "b.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.531911Z",
      "updated_at": "2015-01-17T13:26:17.531911Z"
    }
  ]
}

Delete a zone

To delete a zone by :id use:

DELETE /zone/:id

Parameters:

  • :id - Zone ID (integer)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        -X DELETE \
        https://api.luadns.com/v1/zones/3

Server returns deleted zone:

{
  "id": 3,
  "name": "example.org",
  "synced": false,
  "queries_count": 0,
  "records_count": 3,
  "aliases_count": 0,
  "redirects_count": 0,
  "forwards_count": 0,
  "template_id": 0,
  "records": [
    {
      "id": 6683,
      "name": "example.org.",
      "type": "SOA",
      "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421501178 1200 120 604800 3600",
      "ttl": 3600,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.52747Z",
      "updated_at": "2015-01-17T13:26:17.527471Z"
    },
    {
      "id": 6684,
      "name": "example.org.",
      "type": "NS",
      "content": "a.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.529741Z",
      "updated_at": "2015-01-17T13:26:17.529741Z"
    },
    {
      "id": 6685,
      "name": "example.org.",
      "type": "NS",
      "content": "b.ns.luadns.net.",
      "ttl": 86400,
      "zone_id": 3,
      "created_at": "2015-01-17T13:26:17.531911Z",
      "updated_at": "2015-01-17T13:26:17.531911Z"
    }
  ]
}

Records

The records endpoint allows you to list/add/get/update/delete zone records.

List records

List all records for a zone:

GET /:zone_id/records

Parameters:

  • :zone_id - Zone ID (integer)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/3

The server returns an array containing the records for zone :zone_id:

[
  {
    "id": 6683,
    "name": "example.org.",
    "type": "NS",
    "content": "b.ns.luadns.net.",
    "ttl": 86400,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.522452Z",
    "updated_at": "2015-01-17T13:08:37.522452Z"
  },
  {
    "id": 6684,
    "name": "example.org.",
    "type": "NS",
    "content": "a.ns.luadns.net.",
    "ttl": 86400,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.520623Z",
    "updated_at": "2015-01-17T13:08:37.520623Z"
  },
  {
    "id": 6685,
    "name": "example.org.",
    "type": "SOA",
    "content": "a.ns.luadns.net. hostmaster.luadns.com. 1421500118 1200 120 604800 3600",
    "ttl": 3600,
    "zone_id": 3,
    "created_at": "2015-01-17T13:08:37.519019Z",
    "updated_at": "2015-01-17T13:08:37.519019Z"
  }
]

Create a record

To create a new record on zone identified by :zone_id POST your JSON encoded data:

POST /zones/:zone_id/records

Parameters:

  • :zone_id - Zone ID (integer)
  • name - name (string, required)
  • type - type (string, required)
  • content - content (string, required)
  • ttl - TTL (integer, required)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        -X POST \
        -d '<json>' \
        https://api.luadns.com/v1/zones/1/records

The server will validates your input returns the new record on successful creation:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Get a record

To retrieve a record by :id from zone identified by :zone_id use:

GET /zones/:zone_id/records/:id

Parameters:

  • :zone_id - Zone ID (integer)
  • :id - Record ID (integer)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        https://api.luadns.com/v1/zones/1/records/100

The server returns the record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Update a record

To update a record :id from zone identified by :zone_id use:

PUT /zones/:zone_id/records/:id

Parameters:

  • :zone_id - Zone ID (integer)
  • :id - Record ID (integer)
  • name - name (string, required)
  • type - type (string, required)
  • content - content (string, required)
  • ttl - TTL (integer, required)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        -X PUT \
        -d '<json>'
        https://api.luadns.com/v1/zones/1/records/100

The server returns the updated record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}

Delete a record

To delete a record by :id from zone identified by :zone_id use:

DELETE /zones/:zone_id/records/:id

Parameters:

  • :zone_id - Zone ID (integer)
  • :id - Record ID (integer)

Example:

$ curl -u <email>:<token> \
        -H 'Accept: application/json' \
        -X DELETE \
        https://api.luadns.com/v1/zones/1/records/100

The server returns deleted record:

{
  "id": 100,
  "name": "example.com.",
  "type": "MX",
  "content": "10 mail.example.com.",
  "ttl": 300,
  "zone_id": 1,
  "created_at": "2015-01-17T14:04:35.251785849Z",
  "updated_at": "2015-01-17T14:04:35.251785972Z"
}
Powered by Jekyll