Dynamic DNS

Revision as of 15:41, 14 December 2012

Production API Environment

The production hostname for the DDNS service is https://cprest-vip.hostway.com

Authentication

• HTTP Basic Auth with DDNS username and password as described in RFC 2617

GET /ddns/clients/{client_key}

Returns client details

Request body

No body

Response

• 200 - OK

{ 
  "offline": true
  "hosts": {
    "rel": "related",
    "href": "http://{api_server}/ddns/clients/{client_key}/hosts"
  }
}

• 401 - Unauthorized
• 404 - Not Found

PUT /ddns/clients/{client_key}

Registers new client if the specified client key is not yet registered. When the offline status is set to True all associated hosts are set with the "offline" IP address. When the offline status is changed from True to False all associated hosts are set with the current IP address of the client as seen by the server.

Request body

{ 
  "offline": false
}

Response

• 200 - Existing client status was successfully updated
  • Response body:

{ 
  "offline": false, 
  "hosts": {
    "href": "http://{api_server}/ddns/clients/{client_key}/hosts", 
    "rel": "related"
  }
}

• 201 - New client was successfully registered
  • Response Headers:
    • Location: http://{api_server}/ddns/clients/{client_key}
• 400 - Bad Request
• 401 - Unauthorized

DELETE /ddns/clients/{client_key}

Deletes a client registration

Request body

No body

Response

• 204 - Client was successfully processed
• 401 - Unauthorized
• 404 - Not Found

GET /ddns/clients/{client_key}/hosts

Returns list of all hosts associated with the client

Request body

No body

Response

• 200 - OK
  • Response body:

{ 
  "hosts": [
    "hostname": "{hostname}"
    "ipAddress": "{ipaddr}"
    "links": [
      {
        "rel": "self",
        "href": "http://{api_server}/ddns/clients/{client_key}/hosts/{hostname}"
      }
    ]
  ]
}

• 401 - Unauthorized
• 404 - Not Found

PUT /ddns/clients/{client_key}/hosts/{hostname}

Attach a host (it's actually "connecting a host to client", the host should exist before)

Request body

{ 
}

Response

• 201 - Host was successfully attached
  • Response headers:
    • Location: http://{api_server}/ddns/clients/{client_key}/hosts/{hostname}
• 401 - Unauthorized
• 404 - The host is not registered for DDNS

DELETE /ddns/clients/{client_key}/hosts/{hostname}

Detach a host

Request body

No body

Response

• 204 - Successfully detached
• 401 - Unauthorized
• 404 - Not Found

POST /ddns/clients/{client_key}/action

Perform an action

Request body

{ 
  "{action_name}": "{action_value}" 
}

Actions

• "updateIP" action
  • "default" value - Update the IP address of all registered hosts with the current IP address of the client as seen by the server.

Response

• 204 - Success
• 401 - Unauthorized
• 404 - Not Found

POST /ddns/clients/{client}/hosts/{hostname}/action

Actions performed when processing the call:

• if {client} does not exists, register it
• if {client}.offline = 1, set it to 0
• if {hostname} is not found, return error
• if {hostname} isn't attached to the client, attach it ({hostname} should be enabled in the user portal for DDNS)
• update {hostname} DNS with the remote IP
• update {client} current_ip with the remote IP

Request body

{
  "updateIP": "default"
}

Response

• 204 - Success
• 401 - Unauthorized
• 404 - Not Found