GSLB.me comes with a fully-fledged REST API to manage your DNS services. Using the API you can add, modify, delete, enable and disable domains (GSLB.me refers to DNS domains as “zones“) and records. You can also manage your geohosts and more features are scheduled for next releases.

What is REST?

REST (REpresentational State Transfer) is an HTTP-based protocol: using standard HTTP methods such as GET, POST, PUT and DELETE it allows for remote method/procedure calls. What REST allows you to do is to develop your own client-side code that interacts with GSLB.me to dynamically provision and orchestrate your DNS services.

To read and learn more on REST you can have a look at Wikipedia

Authentication

All API requests must be authenticated: credentials are your username (in the form of the e-mail address you used to register to GSLB.me) and your password. When you first create your account on GSLB.me the API password is set identical to the web GUI password. It is then possible to modify it through the web GUI itself.

Authentication is performed by adding to each API request a standard Basic HTTP Authorization header.

The Authorization header can be created as follows:

  1. Username and password are combined into a string in the form “username:password”
  2. The resulting string (without quotes) is then encoded using Base64
  3. The HTTP “Authorization” header is added to the API request. It must be named “Authorization” and its value must be “Basic” followed by one space character, followed by the Base64-encoded string

For instance, if your username is “username@mysite.com” and your password is “mypassword”, we would have:

  1. Username and password are combined into “username@mysite.com:mypassword”
  2. The string “username@mysite.com:password” without quotes is encoded using Base64
  3. The HTTP “Authorization” header is formed as follows:
Authorization: Basic dXNlcm5hbWVAbXlzaXRlLmNvbTpteXBhc3N3b3JkCg==

This can be easily generated using the standard bash shell:

user ~ $ echo "username@mysite.com:mypassword" | base64
dXNlcm5hbWVAbXlzaXRlLmNvbTpteXBhc3N3b3JkCg==

Content types

An “Accept” HTTP header can be specified for GET requests. Such header tells the API to encode its output using json or XML. The “Accept” header can be set to any of:

Accept: application/json
Accept: application/xml

If the “Accept” header is omitted in the request, json encoding is used by default.

API endpoint

The endpoint URL for the API is:

https://api.gslb.me

HTTPS is mandatory, HTTP is not supported due to security reasons.

API response codes

Every API response includes an HTTP status code. The status code provides information on whether and how the request was successfully processed. In case of errors the status code details what went wrong.

The API can return the following HTTP status codes:

200 - OK (API call successfully completed)
400 - Bad Request (Incorrect request format / Wrong parameters)
401 - Unauthorized (Each API request must be authenticated via HTTP Basic Auth)
403 - Forbidden (The request is not allowed)
404 - Not found (The requested method does not exist / The requested object does not exist)
406 - Not Acceptable (The "Accept" request header was set to an invalid value)
411 - Length Required (A "PUT" or "POST" method was called without specifying the header "Content-Length: 0")
500 - Server Error (An internal error occurred, contact support)
503 - Service Unavailable (Currently unable to service your request / Rate limiting your request, try again in a short while)

Every API response includes an HTTP status code. The status code provides information on whether and how the request was successfully processed. In case of errors the status code details what went wrong.

In addition to the HTTP status code, every API response includes a payload that provides more details on the outcome of the request.

API response encoding

The encoding format of API responses can be selected between JSON and XML by adding the “Accept” HTTP header in the request.

To select JSON encoding:

Accept: application/json

To select XML encoding:

Accept: application/xml

If no “Accept” header is specified, the API defaults to JSON encoding.

API Methods – v2.0 (latest)

Version 2.0 of the REST API can handle (click on the gears icons for details):

 

API Methods – v1.0 (deprecated)

Version 1.0 of the REST API is now deprecated, it is documented here to help migration to the latest relase: