DNS/GSLB API

A schema of the DNS/GSLB API.

zones

Description of API commands for a DNS zone.

Properties

  • uuid
    • a unique identifier of a zone
    • Example: "01234567-89ab-cdef-0123-456789abcdef"
    • Type: string
    • ReadOnly: true
  • name
    • a unique name of a zone
    • Example: "example.com"
    • Type: string
    • Pattern: /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
  • description
    • a description of a zone
    • Example: "my zone"
    • Type: string
  • default_ttl
    • default ttl
    • Example: 30000
    • Type: integer
  • created_at
    • a date & time the resource is created
    • Example: "2015-08-01T00:00:03+09:00"
    • Type: string
    • Format: date-time
  • updated_at
    • a date & time the resource is updated
    • Example: "2015-08-01T00:00:00+09:00"
    • Type: string
    • Format: date-time
  • authenticated
    • Whether the zone is authenticated or not.
    • Type: boolean
  • records
    • Type: array

POST /zones

Creates a new zone.

  • name
    • a unique name of a zone
    • Example: "example.com"
    • Type: string
    • Pattern: /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
  • email
    • email
    • Example: "test@example.com"
    • Type: string
    • Format: email
  • description
    • a description of a zone
    • Example: "my zone"
    • Type: string
  • default_ttl
    • default ttl
    • Example: 30000
    • Type: integer
POST /zones HTTP/1.1
Content-Type: application/json

{
  "name": "example.com",
  "email": "test@example.com",
  "description": "my zone",
  "default_ttl": 30000
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid": "80ef4bb8-f915-47fa-9e12-5f3b8ce6e181",
  "name": "example.com",
  "default_ttl": 30000,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": null,
  "records": [
    {
      "uuid": "b42fe8ec-1f09-4786-b381-226bfcc33c04",
      "name": "example.com",
      "type": "SOA",
      "content": {
        "dns": "ns01.idcfcloud.com",
        "email": "test.example.com.",
        "serial": 1,
        "refresh": 10800,
        "retry": 3600,
        "expire": 604800,
        "ttl": 3600
      },
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "36ab241e-da82-46b0-9ee5-3b3fa151da0f",
      "name": "example.com",
      "type": "NS",
      "content": "ns01.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "8e578870-f68e-4e32-ad9a-e030bc8e952f",
      "name": "example.com",
      "type": "NS",
      "content": "ns02.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "e0cf0cda-9cde-48a0-8455-eb0837597c7e",
      "name": "example.com",
      "type": "NS",
      "content": "ns03.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    }
  ],
  "description": "my zone",
  "authenticated": false
}

GET /zones

Lists existing zones.

GET /zones HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "80ef4bb8-f915-47fa-9e12-5f3b8ce6e181",
    "name": "example.com",
    "default_ttl": 30000,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "description": "my zone",
    "authenticated": false
  }
]

GET /zones/:uuid

Shows a specified zone.

GET /zones/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "80ef4bb8-f915-47fa-9e12-5f3b8ce6e181",
  "name": "example.com",
  "default_ttl": 30000,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": null,
  "records": [
    {
      "uuid": "b42fe8ec-1f09-4786-b381-226bfcc33c04",
      "name": "example.com",
      "type": "SOA",
      "content": {
        "dns": "ns01.idcfcloud.com",
        "email": "test.example.com.",
        "serial": 1,
        "refresh": 10800,
        "retry": 3600,
        "expire": 604800,
        "ttl": 3600
      },
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "36ab241e-da82-46b0-9ee5-3b3fa151da0f",
      "name": "example.com",
      "type": "NS",
      "content": "ns01.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "8e578870-f68e-4e32-ad9a-e030bc8e952f",
      "name": "example.com",
      "type": "NS",
      "content": "ns02.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "e0cf0cda-9cde-48a0-8455-eb0837597c7e",
      "name": "example.com",
      "type": "NS",
      "content": "ns03.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    }
  ],
  "description": "my zone",
  "authenticated": false
}

PUT /zones/:uuid

Updates zone info.

  • description
    • a description of the zone
    • Example: "my zone"
    • Type: string
  • default_ttl
    • default ttl
    • Example: 30000
    • Type: integer
PUT /zones/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Content-Type: application/json

{
  "description": "my zone2",
  "default_ttl": 30000
}
HTTP/1.1 200 OK

{
  "uuid": "80ef4bb8-f915-47fa-9e12-5f3b8ce6e181",
  "name": "example.com",
  "default_ttl": 3600,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": "2015-08-01T00:00:00+09:00",
  "records": [
    {
      "uuid": "b42fe8ec-1f09-4786-b381-226bfcc33c04",
      "name": "example.com",
      "type": "SOA",
      "content": {
        "dns": "ns01.idcfcloud.com",
        "email": "test.example.com.",
        "serial": 1,
        "refresh": 10800,
        "retry": 3600,
        "expire": 604800,
        "ttl": 3600
      },
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "36ab241e-da82-46b0-9ee5-3b3fa151da0f",
      "name": "example.com",
      "type": "NS",
      "content": "ns01.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "8e578870-f68e-4e32-ad9a-e030bc8e952f",
      "name": "example.com",
      "type": "NS",
      "content": "ns02.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    },
    {
      "uuid": "e0cf0cda-9cde-48a0-8455-eb0837597c7e",
      "name": "example.com",
      "type": "NS",
      "content": "ns03.idcfcloud.com",
      "ttl": 3600,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null,
      "priority": null
    }
  ],
  "description": "my zone2",
  "authenticated": false
}

DELETE /zones/:uuid

Deletes a specified zone.

DELETE /zones/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
HTTP/1.1 200 OK
{}

POST /zones/:uuid/verify

Verifies a specified zone.

POST /zones/01234567-89ab-cdef-0123-456789abcdef/verify HTTP/1.1
HTTP/1.1 200 OK
{}

records

Descriptions of the API commands for DNS records.

Properties

  • uuid
    • a unique identifier of a record.
    • Example: "01234567-89ab-cdef-0123-456789abcdef"
    • Type: string
    • ReadOnly: true
  • name
    • a name of a record
    • Example: "www.example.com"
    • Type: string
  • content
    • Composition of a record
    • Example: "1.1.1.1"
    • Type: string or hash (for a soa record)
  • type
    • a type of a record
    • Example: "A"
    • Type: string
    • Pattern: /^(A|CNAME|AAAA|MX|TXT|SRV)$/
  • ttl
    • ttl
    • Example: 30000
    • Type: integer
  • priority
    • Weight added to the record based on priority
    • Example: 10
    • Type: integer
  • created_at
    • a date & time the resource is created
    • Example: "2015-08-01T00:00:00+09:00"
    • Type: string
    • Format: date-time
  • updated_at
    • a date & time the resource is updated
    • Example: "2015-08-01T00:00:00+09:00"
    • Type: string
    • Format: date-time

GET /zones/:uuid/records

Shows specified zone records.

GET /zones/01234567-89ab-cdef-0123-456789abcdef/records HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "b42fe8ec-1f09-4786-b381-226bfcc33c04",
    "name": "example.com",
    "type": "SOA",
    "content": {
      "dns": "ns01.idcfcloud.com",
      "email": "test.example.com.",
      "serial": 1,
      "refresh": 10800,
      "retry": 3600,
      "expire": 604800,
      "ttl": 3600
    },
    "ttl": 3600,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "priority": null
  },
  {
    "uuid": "36ab241e-da82-46b0-9ee5-3b3fa151da0f",
    "name": "example.com",
    "type": "NS",
    "content": "ns01.idcfcloud.com",
    "ttl": 3600,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "priority": null
  },
  {
    "uuid": "8e578870-f68e-4e32-ad9a-e030bc8e952f",
    "name": "example.com",
    "type": "NS",
    "content": "ns02.idcfcloud.com",
    "ttl": 3600,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "priority": null
  },
  {
    "uuid": "e0cf0cda-9cde-48a0-8455-eb0837597c7e",
    "name": "example.com",
    "type": "NS",
    "content": "ns03.idcfcloud.com",
    "ttl": 3600,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "priority": null
  }
]

POST /zones/:uuid/records

Creates a new record.

  • name
    • a name of a record
    • Example: "www.example.com"
    • Type: string
  • type
    • a type of a record
    • Example: "A"
    • Type: string
    • Pattern: /^(A|CNAME|AAAA|MX|TXT|SRV)$/
  • content
    • Components of the record
    • Example: "1.1.1.1"
    • Type: string
  • ttl
    • ttl
    • Example: 30000
    • Type: integer
  • priority
    • priority of record
    • Example: 10
    • Type: integer
POST /zones/01234567-89ab-cdef-0123-456789abcdef/records HTTP/1.1
Content-Type: application/json

{
  "name": "www.example.com",
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 3600
}
{
  "name": "cname.example.com",
  "type": "CNAME",
  "content": "www.example.com",
  "ttl": 3600
}
{
  "name": "ip6.example.com",
  "type": "AAAA",
  "content": "2001:cdba:0000:0000:0000:0000:3257:9652",
  "ttl": 3600
}
{
  "name": "mx.example.com",
  "type": "MX",
  "content": "www.example.com",
  "priority": 10,
  "ttl": 3600
}
{
  "name": "_sip._udp.example.com",
  "type": "SRV",
  "content": "1 5060 sip.example.com",
  "priority": 10,
  "ttl": 3600
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid": "e46466a6-377c-4b5a-84b2-f93f3a8d09eb",
  "name": "www.example.com",
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 3600,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": null,
  "priority": null
}

GET /zones/:uuid/records/:uuid

Shows a specified record.

GET /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "www.example.com",
  "content": "1.1.1.1",
  "type": "A",
  "ttl": 30000,
  "description": "my record",
  "default_ttl": 30000,
  "priority": 10,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": null
}

PUT /zones/:uuid/records/:uuid

Updates a specified record.

PUT /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Content-Type: application/json
{
  "name": "www.example.com",
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 30000
}

Updates a SOA record.


{
  "content": {
    "email": "test@example.com",
    "ttl": 3600
  }
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "www.example.com",
  "content": "192.168.1.1",
  "type": "A",
  "ttl": 30000,
  "description": "my record",
  "default_ttl": 30000,
  "priority": 10,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": "2015-08-01T00:00:00+09:00",
}

DELETE /zones/:uuid/records/:uuid

Deletes existing records.

DELETE /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{}

records(GSLB)

Descriptions of API commands for GSLB records.

Properties

Parameters used with the API commands for GSLB records.

  • uuid
    • a unique identifier of a record.
    • Example: "01234567-89ab-cdef-0123-456789abcdef"
    • Type: string
    • ReadOnly: true
  • name
    • a name of a record
    • Example: "www.example.com"
    • Type: string
    • Required: true
  • type
    • a type of a record
    • Example: "A"
    • Type: string
    • Pattern: /^(A)$/
    • Required: true
  • content
    • Components of a record
    • Example: "1.1.1.1"
    • Type: string
    • Required: true
  • ttl
    • ttl
    • Example: 5
    • Type: integer
    • Required: true
  • weight
    • Weight added to a record based on priority
    • Example: 1
    • Type: integer
    • Required: true
  • description
    • Example: "This is to..."
    • Type: string
    • Required: false
    • Default: blank
  • created_at
    • a date & time the resource is created
    • Example: "2015-08-01T00:00:00+09:00"
    • Type: string
    • Format: date-time
    • ReadOnly: true
  • updated_at
    • a date & time the resource is updated
    • Example: "2015-08-01T00:00:00+09:00"
    • Type: string
    • Format: date-time
    • ReadOnly: true
  • healthcheck
    • detailed info about the health check
    • Type: hash
    • Set null or false when health check is not needed.
    • Required: false
    • ip
      • an IP address a health check is conducted on
      • Example: "1.1.1.1"
      • Type: string
      • Required: false
      • Default: the value set for the "content" is set
    • auto_failback
      • flag to show auto failback is enabled
      • Example: 1
      • Type: integer
      • Required: true
    • parameters
      • detailed health check parameters contained
      • common parameters for the GSLB records under the same name (this field can be omitted if they have already been set under the same name.)
      • Type: hash
      • Required: true
      • type
        • a type of health check: http, https, or tcp
        • Type: string
        • Required: true
      • port
        • a port health check is conducted
        • Type: integer
        • Required: true
      • host
        • a host name for a virtual host which a health check is to be conducted
        • Type: string
        • Required: false
        • Default: no value
      • path
        • a path for which a health check is to be conducted
        • Type: string
        • Required: false
        • Default: "/"
      • interval
        • a length of interval (in sec) a health check is conducted at
        • the value must be set higher than that for a timeout.
        • Type: integer
        • Required: true
      • timeout
        • a timeout (in sec) for a health check
        • Type: integer
        • Required: true
      • occurrences
        • a threshold of number of health check errors
        • Type: integer
        • Required: true
      • notification_group
        • notification group uuid
        • Type: string
        • Required: false
        • Default: null

POST /zones/:uuid/records

Creates a new GSLB record using either of the following parameters.

  • name
  • type
  • content
  • ttl
  • weight
  • description (optional)
  • healthcheck (optional)
    • ip
    • auto_failback
    • parameters
      • type
      • port
      • host (optional)
      • path (optional)
      • interval
      • timeout
      • occurrences
      • notification_group (optional)
POST /zones/01234567-89ab-cdef-0123-456789abcdef/records HTTP/1.1
Content-Type: application/json

{
  "name": "gslb.example.com",
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 5,
  "weight": 1,
  "description": "",
  "healthcheck": {
    "auto_failback": 1,
    "ip": "192.168.1.1",
    "parameters": {
        "type": "http",
        "port": 80,
        "host": "www.example.com",
        "path": "/hc.txt",
        "interval": 60,
        "timeout": 3,
        "occurrences": 5,
        "notification_group": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid":"01234567-89ab-cdef-0123-456789abcdef",
  "name":"gslb.example.com",
  "type":"A",
  "content":"192.168.1.1",
  "ttl":5,
  "weight":1,
  "description":"",
  "created_at":"2016-10-04T16:38:12+09:00",
  "updated_at":"2016-10-04T16:38:12+09:00",
  "healthcheck": {
    "auto_failback":1,
    "ip":"192.168.1.1",
    "parameters": {
      "type":"http",
      "port":80,
      "host":"www.example.com",
      "path":"\/hc.txt",
      "interval":60,"
      "timeout":3,
      "occurrences":5,
      "notification_group":"01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

GET /zones/:uuid/records/:uuid

Shows a specified record.

GET /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid":"01234567-89ab-cdef-0123-456789abcdef",
  "name":"gslb.example.com",
  "type":"A",
  "content":"192.168.1.1",
  "ttl":5,
  "weight":1,
  "description":"",
  "created_at":"2016-10-04T16:38:12+09:00",
  "updated_at":"2016-10-04T16:38:12+09:00",
  "healthcheck": {
    "auto_failback":1,
    "ip":"192.168.1.1",
    "parameters": {
      "type":"http",
      "port":80,
      "host":"www.example.com",
      "path":"\/hc.txt",
      "interval":60,"
      "timeout":3,
      "occurrences":5,
      "notification_group":"01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

PUT /zones/:uuid/records/:uuid

Updates a specified record using either of the following parameters.

  • content
  • ttl
  • weight
  • description
  • healthcheck
    • ip
    • auto_failback
    • parameters
      • type
      • port
      • host
      • path
      • interval
      • timeout
      • occurrences
      • notification_group
PUT /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Content-Type: application/json

{
  "content": "192.168.1.2",
  "ttl": 5,
  "weight": 2,
  "description": "",
  "healthcheck": {
    "auto_failback": 1,
    "ip": "192.168.1.1",
    "parameters": {
        "type": "http",
        "port": 80,
        "host": "www.example.com",
        "path": "/healthcheck.txt",
        "interval": 60,
        "timeout": 3,
        "occurrences": 5,
        "notification_group": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid":"01234567-89ab-cdef-0123-456789abcdef",
  "name":"gslb.example.com",
  "type":"A",
  "content":"192.168.1.2",
  "ttl":5,
  "weight":2,
  "description":"",
  "created_at":"2016-10-04T16:38:12+09:00",
  "updated_at":"2016-10-04T17:08:25+09:00",
  "healthcheck": {
    "auto_failback":1,
    "ip":"192.168.1.1",
    "parameters": {
      "type":"http",
      "port":80,
      "host":"www.example.com",
      "path":"\/healthcheck.txt",
      "interval":60,"
      "timeout":3,
      "occurrences":5,
      "notification_group":"01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

DELETE /zones/:uuid/records/:uuid

Deletes a specified record.

DELETE /zones/01234567-89ab-cdef-0123-456789abcdef/records/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{}

templates

Properties

  • uuid
    • a unique identifier of a templates
    • Example: "01234567-89ab-cdef-0123-456789abcdef"
    • Type: string
    • ReadOnly: true
  • name
    • a unique name of a template
    • Example: "example.com"
    • Type: string
    • Pattern: /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
  • description
    • a description of a template
    • Example: "my templates"
    • Type: string
  • default_ttl
    • default ttl
    • Example: 30000
    • Type: integer
  • created_at
    • a date & time the resource is created
    • Example: ""
    • Type: string
    • Format: date-time
  • records
    • Type: array

GET /templates

Shows a specified template.

GET /templates HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example.com",
    "description": "my templates",
    "default_ttl": 30000,
    "created_at": "2015-08-01T00:00:00+09:00",
    "updated_at": null,
    "records": [
      {
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "www.example.com",
        "content": "1.1.1.1",
        "type": "A",
        "description": "my zone",
        "ttl": 30000,
        "priority": 10,
        "created_at": "2015-08-01T00:00:00+09:00",
        "updated_at": null
      }
    ]
  }
]

GET /templates/:uuid

Lists existing template.

GET /templates/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example.com",
  "description": "my templates",
  "default_ttl": 30000,
  "created_at": "2015-08-01T00:00:00+09:00",
  "updated_at": null,
  "records": [
    {
      "uuid": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "www.example.com",
      "content": "1.1.1.1",
      "type": "A",
      "description": "my zone",
      "default_ttl": 30000,
      "priority": 10,
      "created_at": "2015-08-01T00:00:00+09:00",
      "updated_at": null
    }
  ]
}

notifications

GET /notifications

Lists existing notification groups.

GET /notifications HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "default"
  },
  {
    "uuid": "11234567-89ab-cdef-0123-456789abcdef",
    "name": "group01"
  }
]