To connect to the API a HTTP request has to be made at the API location.
The API is available on two different locations; a production environment and a test environment.
For authentication, there are 2 methods available: HTTP Basic authentication and session keys.
HTTP Basic access authentication
The username is a combination of your customer handle, and the login name of the user you want to use. The password is the password of this user.
Customer handle: your_customer_handle
User login name: your_designated_user
The username would be: your_customer_handle/your_designated_user
The password would be: secret123
The final result will be a combined string "username:password", which will then be Base64 encoded and supplied in the Authorization header:
Combined encoded: eW91cl9jdXN0b21lcl9oYW5kbGUveW91cl9kZXNpZ25hdGVkX3VzZXI6c2VjcmV0MTIz
Authorization: Basic eW91cl9jdXN0b21lcl9oYW5kbGUveW91cl9kZXNpZ25hdGVkX3VzZXI6c2VjcmV0MTIz
For more information about this subject please visit: wikipedia.org/wiki/Basic_access_authentication
It is possible to create a user session, which will return a session key. When you supply this key with your requests, the request will be authenticated.
Please note that session keys will remain valid for 30 minutes since the last action which used the key.
You can supply the session key in a HTTP header:
Authorization: Session XABQ6MKI6GLSTVX0DWNO
See Create Session for instructions on creating a session key.
The API supports GET, POST and DELETE requests. GET is used to query the system (retrieve information). POST is used when modifying data (e.g. update a domain). DELETE is used to delete objects.
For POST requests, the body of each request should be entirely JSON encoded.
For further documentation about JSON please visit: JSON.org
All leading and trailing white spaces from string based values will be stripped.
The API responses will be JSON encoded as well.
Please note that the DateTime format used in requests and responses is in the following format: yyyy-MM-dd'T'HH:mm:ssZZ
The time zone offset is 'Z' for zero, and of the form '±HH:mm' for non-zero.
Most commands require additional parameters to be supplied with the request.
For example a domain create command requires nameserver data and contact handles.
Those parameters should be supplied inside the JSON body of the POST request.
A list of all available parameters for each request can be found at the specific request pages.
The API gives out different response codes, based on the result of the request:
200: Request received, the body contains the status of the request.
201: Request received, object is created. The URI for the new object is returned.
400: Error: general error, additional information is returned in the response body.
401: Error: unauthorized, additional information may be returned in the response body.
404: Error: resource not found, additional information may be returned in the response body.
415: Error: invalid media type, possibly missing Content-Type header
5xx: Error: Any server-side error.
The API response body is formatted using JSON.
When a requests creates a process a "X-Process-Id" header will be included in the response with the ID of the process.