Need help? Call Live Support at +31 (0) 38 453 07 59

Connection

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.

Production: https://api.yoursrs.com/
Test: https://api.yoursrs-ote.com/

Authentication

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.
Example:

Customer handle: your_customer_handle
User login name: your_designated_user
Password: secret123

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: your_customer_handle/your_designated_user:secret123
Combined encoded: eW91cl9jdXN0b21lcl9oYW5kbGUveW91cl9kZXNpZ25hdGVkX3VzZXI6c2VjcmV0MTIz
Final header:

Authorization: Basic eW91cl9jdXN0b21lcl9oYW5kbGUveW91cl9kZXNpZ25hdGVkX3VzZXI6c2VjcmV0MTIz

For more information about this subject please visit: wikipedia.org/wiki/Basic_access_authentication

Session keys

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.

Requests

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.

JSON

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.

DateTime format

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.

Parameters

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.

Responses

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.