The management of hosts via REST API Gateway allows for easy checking, creation, deleting, and updating of name servers.

Host management commands can be applied only to the host name objects that have a subordinate relationship to a superordinate domain name, in other words – registrar is able to manage only host name objects related to the domain names within his domain repository in ST Registry.

1. Check Host availability

Host check command is used to determine if a name server host exists. It provides a hint that allows a client to anticipate the success or failure of provisioning, changing or deleting a name server host object.

Command provide possibility to check one(1) hostname per request.

URI: /hosts/:name/check
Request method: GET

Name	Description
name	Host name

Request example:

After successful request, response will contain following elements:

• avail – identify if host name available for registration/creation or not. 0 – not available. 1 – available
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

2. Create Host

Name server hosts can be created using the Host create command. Request body may include:

• name – element that contains the fully qualified name of a host. This value is obligatory.
• addr – elements that contain collection of IP addresses to be associated with the host which should be represented in pairs key->value.
  • Key may obtain value “v4” or “v6” which identify IP version.
  • Value should represent IP in version that is identified by Key.

URI: /hosts

Request method: PUT

Request example:

After successful request, response will contain following elements:

• name – created host name.
• crDate – date and time when host was created.
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

3. Query Host

Host query command is used to retrieve information associated with a host object.

URI: /hosts/:name
Request method: GET

Name	Description
name	Host name

Request example:

After successful request, response will contain following elements:

• name – host name queried in this request.
• clID – ClientID – current host sponsor.
• crID – ClientID – host creator.
• crDate – date when host was created.
• addr – elements that contain collection of IP addresses associated with current host which is represented in pairs key->value.
  • Key may obtain value “v4” or “v6” which identify IP version.
  • Value should represent IP in version that is identified by Key.
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

4. Update Host

Host update command allows modification of attributes in existing host object. Request body may contain following elements/instructions:

• add – optional element that contains attribute values to be added to the object.
• rem – optional element that contains attribute values to be removed from the object.
• chg – instruction is not used in host update command, updates to the host object are performed only by using “add” and “rem” instruction. If registrar would like to update some attribute like IP address – he will need to delete old and add new one.

URI: /hosts/:name

Request method: POST

Name	Description
name	Host name

Request example:

In request example below we have provided all possible host attributes that is possible to update.

After successful request, response will contain following elements:

• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

5. Delete Host

Host delete command is supposed to be used to delete Host object. Only object sponsor/owner may delete it (refer to clID attribute).

If contact have a status “clientDeleteProhibited” or “serverDeleteProhibited” then Host delete request will be rejected. Also, request will be rejected if host is linked with another object in a Registry repository.

URI: /hosts/:name
Request method: DELETE

Name	Description
name	Host name

Request example:

After successful request, response will contain following elements:

• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

6. Host status codes

Same as for domain objects there is 2 different types of status codes: client and server codes. Client status codes are set by registrars. Server status codes are set by ST Registry and they take precedence over client codes.

The following are two tables containing 10 possible host object status codes, these tables will explain what each status means.

Server codes:

Status code	Description
ok	This is the standard status for a domain, meaning it has no holds or restrictions. This status code is set and removed by ST Registry as other status values are added or removed.
linked	The host object has at least one active association with a domain object. Registrars are unable to delete such host object unless all associations between host object and domains will be destroyed. To find all domains with association to corresponding host object please refer to the manual – Collections.
serverDeleteProhibited	Any request to delete host object will be rejected by ST Registry.
serverUpdateProhibited	Any request to update host object (other than to remove this status) will be rejected by ST Registry.
pendingCreate	This status code indicates that a request to create host object has been received and is being processed. Status is removed when host object will be propagated to the root ST zone.
pendingUpdate	This status indicates that a request to update host object has been received and is being processed. Status is removed when host object updates will be propagated to the root ST zone.
pendingTransfer	This status indicates that a request to transfer the host object superordinate domain object has been received and is being processed.
pendingDelete	This status indicates that a request to delete host object has been received and is being processed. Status code is removed and host object completely deleted from ST Registry repository after changes propagated to the root ST zone.

 

7. Response codes

To simplify initial integration process, instead of general error messages, ST Registry provide different response messages for same response code depending from exception which generated corresponding response code. Below you can find list of all possible response codes and their messages for host related operations.

Response code	Message
1000	Command completed successfully
2003	Missing host name
2005	Invalid host:name
2005	Invalid host:addr
2203	Operation not permitted
2302	Host already exists
2302	Host with name {hostaname} already exists
2304	Object status prohibits operation
2305	Host must be subordinate to one of the registrar domains