You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 18
Next »
Instructions for the complete automation of the registration of a domain, using the example of the domain example.com.
.com is a generic top-level domain, which is well suited for the first implementation due to the lack of restrictions.
Basics of the JSON and XML API
All important information for the use of the JSON and XML API can be found under the following links:
Process Overview
Flow Chart
Tasks Names, Codes and Routes
| Task | Code | Route |
|---|
| ContactCreate | 0301 | POST /contact |
| DomainCreate | 0101 | POST /domain |
| PollInfo | 0905 | GET /poll |
| PollConfirm | 0906 | PUT /poll/$id |
| DomainInfo | 0105 | GET / domain/$name |
Requirements
Domain Contacts
To order a .com domain you need a domain owner (OwnerC), an administrative contact (AdminC) and a technical contact (TechC). You can use existing contacts or create new ones.
ContactCreate - Example
POST /contact
{
"type": "PERSON",
"fname": "John",
"lname": "Doe",
"organization": "Company",
"address": [
"123 Main Street"
],
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY",
"phone": "+49-0-0",
"email": "john.doe@domain.com"
}
{
"stid": "20180926-app3-dev-4889",
"status": {
"code": "S0301",
"text": "Domain contact has been successfully created.",
"type": "SUCCESS"
},
"object": {
"type": "handle",
"value": "23102255"
},
"data": [
{
"created": "2018-09-26T15:18:53.000+0200",
"updated": "2018-09-26T15:18:53.000+0200",
"id": 23102255,
"owner": {
"user": "USER",
"context": CONTEXT
},
"updater": {
"user": "USER",
"context": CONTEXT
},
"alias": "John-Doe",
"type": "PERSON",
"fname": "John",
"lname": "Doe",
"organization": "Company",
"address": [
"123 Main Street"
],
"pcode": "12345",
"city": "Anytown",
"country": "DE",
"state": "BY",
"phone": "+49-0-0",
"email": "john.doe@domain.com",
"protection": "SHOW_NONE"
}
]
}
<request>
<auth>
<user>USER</user>
<password>PASSWORD</password>
<context>CONTEXT</context>
</auth>
<task>
<code>0301</code>
<handle>
<type>PERSON</type>
<fname>John</fname>
<lname>Doe</lname>
<organization>Anycorp</organization>
<address>Anystreet</address>
<pcode>12345</pcode>
<city>Anytown</city>
<country>DE</country>
<state />
<phone>+49-0-0</phone>
<fax>+49-0-0</fax>
<email>john.doe@domain.com</email>
</handle>
</task>
</request>
<response>
<result>
<data />
<status>
<code>S0301</code>
<text>Domain contact has been successfully created.</text>
<type>success</type>
<object>
<type>handle</type>
<value>100</value>
</object>
</status>
</result>
<stid>20180926-stid</stid>
</response>
Process
Registering domains is an asynchronous process because the registry is involved in the processing of the order. The order notifications are provided in the system upon receipt and can be retrieved by polling.
Starting DomainCreate Request
With the request type DomainCreate you start the registration of the domain. The following values are required:
- Contacts: The contact ID of the required contacts. For .com domains, a domain owner, an administrative contact and a technical contact are required.
- Domain: The name of the domain
- Name server: The desired name servers. The number of name servers required depends on the TLD.
Domain Create - Example
POST /domain
{
"name": "example.com",
"ownerc": {
"id": 100
},
"adminc": {
"id": 100
},
"techc": {
"id": 100
},
"nameServers": [
{
"name": "a.ns14.net"
},
{
"name": "b.ns14.net"
},
{
"name": "c.ns14.net"
},
{
"name": "d.ns14.net"
}
]
}
{
"stid": "20180926-stid",
"status": {
"code": "N0101",
"text": "Domain registration was started successfully.",
"type": "NOTIFY"
},
"object": {
"type": "domain",
"value": "example.com"
}
}
<request>
<auth>
<user>USER</user>
<password>PASSWORD</password>
<context>CONTEXT</context>
</auth>
<task>
<code>0101</code>
<domain>
<name>example.com</name>
<ownerc>100</ownerc>
<adminc>100</adminc>
<techc>100</techc>
<nserver>
<name>a.ns14.net</name>
</nserver>
<nserver>
<name>b.ns14.net</name>
</nserver>
<nserver>
<name>c.ns14.net</name>
</nserver>
<nserver>
<name>d.ns14.net</name>
</nserver>
<confirm_order>1</confirm_order>
<period>1</period>
</domain>
</task>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>
<data>
<domain_job>
<job>
<id>123456</id>
<status>RUNNING</status>
</job>
</domain_job>
</data>
<status>
<code>N0101</code>
<text>Domain registration was started successfully.</text>
<type>notify</type>
<object>
<type>domain</type>
<value>example.com</value>
</object>
</status>
</result>
<stid>20180926-stid</stid>
</response>
Checking and confirming Notifications
The order type DomainCancelationCreate creates a cancelation request. This triggers the creation of a second cancelation request, which is processed asynchronously at the time defined in the cancelation.
Once this second requst has been processed, a request notification is sent, indicating whether the deletion was successful or not.
You must call the notification with the PollInfo task. You must confirm the retrieval with the PollConfirm task.
PollInfo - Examples
{
"stid": "20180926-stid",
"status": {
"code": "S0905",
"text": "The notification was polled successfully.",
"type": "SUCCESS"
},
"object": {
"type": "message",
"value": "1819917"
},
"data": [
{
"summary": 1,
"message": {
"id": 1819917,
"job": {
"id": 4295609745,
"domain": {
"created": "2018-09-26T15:11:21.000+0200",
"owner": {},
"updater": {},
"name": "example.com",
"expire": "2019-09-26T15:11:20.000+0200",
"payable": "2019-09-26T15:11:21.000+0200",
"ownerc": {
"id": 100
},
"adminc": {
"id": 100
},
"techc": {
"id": 100
},
"registryStatus": "LOCK",
"nameServers": [
{
"name": "a.ns14.net"
},
{
"name": "b.ns14.net"
},
{
"name": "c.ns14.net"
},
{
"name": "d.ns14.net"
}
],
"lastAction": "CREATE",
"authinfo": "gg9o3FFL/hzNbuPw",
"autoRenewStatus": "TRUE",
"registrarStatus": "ACTIVE",
"rddsOptIn": "NOT_SET"
}
},
"stid": "20180926-stid",
"object": {
"type": "domain",
"value": "example.com"
},
"status": {
"code": "S0101",
"type": "SUCCESS"
}
}
}
]
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0905</code>
</task>
</request>
<response>
<result>
<data>
<summary>1</summary>
<message>
<id>1855680</id>
<owner>
<user>alex_normal_plus</user>
<context>4</context>
</owner>
<job>
<domain>
<name>example.com</name>
<expire>2019-10-15 14:02:40</expire>
<payable>2019-10-15 14:02:41</payable>
<ownerc>100</ownerc>
<adminc>100</adminc>
<techc>100</techc>
<nic_member_label>VGRS-TEST</nic_member_label>
<registry_status>LOCK</registry_status>
<nserver>
<name>a.ns14.net</name>
</nserver>
<nserver>
<name>b.ns14.net</name>
</nserver>
<nserver>
<name>c.ns14.net</name>
</nserver>
<nserver>
<name>d.ns14.net</name>
</nserver>
<period>1</period>
<authinfo>S0Lygv+ZkNbniICm</authinfo>
<autorenew>true</autorenew>
<confirm_order>1</confirm_order>
<confirm_owner_consent>0</confirm_owner_consent>
<registrar_status>ACTIVE</registrar_status>
<rdds_opt_in>NOT_SET</rdds_opt_in>
<owner/>
<updater/>
<created>2018-10-15 14:02:41</created>
</domain>
<job_id>4295625406</job_id>
<status>
<code>S0101</code>
<type>success</type>
<object>
<type>domain</type>
<value>example.com</value>
</object>
</status>
<stid>20181015-app1-3788</stid>
</job>
<created>2018-10-15 14:03:02</created>
</message>
</data>
<status>
<code>S0905</code>
<text>The notification was polled successfully.</text>
<type>success</type>
<object>
<type>message</type>
<value>1855680</value>
</object>
</status>
</result>
<stid>20181015-app1-3805</stid>
</response>
PollConfirm - Examples
{
"stid": "20180926-stid",
"status": {
"code": "S0906",
"text": "The notification was confirmed successfully.",
"type": "SUCCESS"
},
"object": {
"type": "message",
"value": "1819853"
}
}
<request>
<auth>
<user>USER</user>
<context>CONTEXT</context>
<password>PASSWORD</password>
</auth>
<task>
<code>0906</code>
<message>
<id>650664</id>
</message>
</task>
</request>
<response>
<result>
<data>
<summary>0</summary>
<message>
<id>650664</id>
</message>
</data>
<status>
<code>S0906</code>
<text>The notification was confirmed successfully.</text>
<type>success</type>
<object>
<type>message</type>
<value>650664</value>
</object>
</status>
</result>
<stid>20181015-app1-3162</stid>
</response>
Inquire Domain Data
After successful registration, you can query the registration data stored in the system with the DomainInfo task. This enables you to determine whether the domain has been registered with the desired data.
{
"stid": "20180926-stid",
"status": {
"code": "S0105",
"text": "Domain data has been inquired successfully.",
"type": "SUCCESS"
},
"object": {
"type": "domain",
"value": "example.com"
},
"data": [
{
"created": "2018-09-26T14:54:03.000+0200",
"updated": "2018-09-26T14:54:10.000+0200",
"owner": {
"user": "USER",
"context": CONTEXT
},
"updater": {
"user": "USER",
"context": CONTEXT
},
"name": "example.com",
"payable": "2021-12-31T00:00:00.000+0200",
"ownerc": {
"id": 100
},
"adminc": {
"id": 100
},
"techc": {
"id": 100
},
"registryStatus": "LOCK",
"nameServers": [
{
"name": "a.ns14.net"
},
{
"name": "b.ns14.net"
},
{
"name": "c.ns14.net"
},
{
"name": "d.ns14.net"
}
],
"trustee": false,
"privacy": false,
"authinfo": "J/w0Xpn66I87YVty",
"domainsafe": false,
"validCertificate": false,
"autoRenewStatus": "TRUE",
"registrarStatus": "ACTIVE",
"rddsOptIn": "NOT_SET"
}
]
}
<request>
<auth>
<user>USER</user>
<password>PASSWORD</password>
<context>CONTEXT</context>
</auth>
<task>
<code>0105</code>
<domain>
<name>example.com</name>
</domain>
</task>
</request>
<response>
<result>
<data>
<domain>
<name>example.com</name>
<payable>2021-12-31 00:00:00</payable>
<ownerc>100</ownerc>
<adminc>100</adminc>
<techc>100</techc>
<registry_status>LOCK</registry_status>
<nserver>
<name>a.ns14.net</name>
</nserver>
<nserver>
<name>b.ns14.net</name>
</nserver>
<nserver>
<name>c.ns14.net</name>
</nserver>
<nserver>
<name>d.ns14.net</name>
</nserver>
<period>1</period>
<status>SUCCESS</status>
<use_trustee>false</use_trustee>
<use_privacy>false</use_privacy>
<authinfo>J/w0Xpn66I87YVty</authinfo>
<domainsafe>false</domainsafe>
<certificate>false</certificate>
<autorenew>true</autorenew>
<registrar_status>ACTIVE</registrar_status>
<rdds_opt_in>NOT_SET</rdds_opt_in>
<owner>
<user>USER</user>
<context>CONTEXT</context>
</owner>
<updater>
<user>USER</user>
<context>CONTEXT</context>
</updater>
<created>2018-09-26 14:54:03</created>
<updated>2018-09-26 14:54:10</updated>
</domain>
</data>
<status>
<code>S0105</code>
<text>Domain data has been inquired successfully.</text>
<type>success</type>
<object>
<type>domain</type>
<value>example.com</value>
</object>
</status>
</result>
<stid>20180926-stid</stid>
</response>