WAPI - Manual

In this article you will learn:

WEDOS API

The WEDOS API, or WAPI, is used to control services directly from your information system. 

A condition for using the interface is the use of a WEDOS deposit account, from which the system deducts payments for registrations, renewals, re-registrations and other fees charged.

WAPI currently allows for the management of:

WAPI limitations

To protect against abuse, WAPI applies the following restrictions:

  • You can send a maximum of 1000 requests per hour via one user account. This applies to all requests of all types, if this limit is reached, WAPI rejects further requests until the time limit expires.
  • One user account is allowed to make a maximum of 100 domain availability requests per hour. This applies to the domain-check, domain-create, and domain-transfer-check commands.
  • Repeatedly sending invalid requests (authorization failure, access from an unauthorized IP address, incorrect input, missing or incorrect parameters, unknown command, commands ending in any error, or any request exceeding other restrictions) will cause the IP address to be blocked for 1 minute for each invalid request if 10 invalid requests are exceeded. With each additional invalid request, the system extends the blocking time.

Synchronous and asynchronous operations

Most commands executed via WAPI are synchronous - you send a command and usually get the result within a few seconds. 

Some operations are asychronous, so it can take a very long time (even hours or days) to process such a command. WAPI will therefore not return the final result, but only information about the receipt of the command. The system then sends you information about the progress and the final result in the form of notifications.

WAPI activation in customer administration

Before you start using WAPI, activate it in the customer administration by following these steps:

  1. Log in to the customer administration ⧉.
  2. Select My Account Customer from the top menu.
  3. Select the WAPI interface from the left menu.
  4. Set the allowed IP addresses, notification method, preferred protocol and password.
  5. Confirm the settings with the Set buttons.
Open WAPI settings
Sample WAPI activation
Sample WAPI activation

You can change all the settings you entered during activation later in the same way. Delete the contents of the Enabled IP Addresses field to deactivate WAPI.

Communication and authentication

Communication with the WAPI interface is via HTTPS protocol. Data is transferred by POST method in request parameter in XML or JSON format. The basic command and response format is the same for all commands. The data encoding is UTF-8.

The URL of the interface:

  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

Structure of the request

The request consists of the following data:

  • user: username (e-mail) of your customer account, mandatory parameter.
  • auth: Authorization string, mandatory parameter. This is a sha1 hash of a string consisting of the username, the sha1 hash of the WAPI password, and the current time (00-23). The time zone is Europe/Prague (winter time UTC+1 CEST, summer time UTC+2 CEST). For a specific example, see the code below.
  • command: the WAPI command itself. Required parameter.
  • clTRID: Request ID, optional parameter. You can insert any string into this element as an identifier that the WAPI will return in the response.
  • data: the data part of the command. Optional parameter.
  • test: test mode flag, optional parameter. If you enter the test element with a value of 1, WAPI will only check your command but will not make any changes.

When communicating with WAPI, please provide the WAPI password. Customer account password does not work.

The request template (JSON) is thus:

{
  "request":
  {
    "user": "váš@login.tld",
    "auth": "autorizační řetězec",
    "command": "název požadavku",
    "data":
    {
      data požadavku
    }
    "clTRID": "identifikátor požadavku (nepovinné)",
    "test": "1 (pokud chcete požadavek jenom testovat, nepovinné)"
  }
}

A complete example of PHP usage (JSON data format) can be:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'váš@login.tld'; 
$wpass = 'vaše heslo k WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'název požadavku',
  'data' => ['pole dat požadavku'],
  'clTRID' => 'identifikátor požadavku (nepovinné)',
  'test' => '1 (pokud chcete požadavek jenom testovat)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Structure of the answer

The answer consists of the following data:

  • code: The return value of the command. For more information, see Return codes.
  • result: Text description of the return code.
  • timestamp: the time the command was executed in UNIX format.
  • clTRID: Client-side command identifier.
  • svTRID: Server-side command identifier.
  • command: WAPI command.
  • data: return values. If the command fails, it does not return data.
  • test: inserted when responding to commands that also contain this flag.

For example, a sample JSON response looks like this:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"	
    },
    "test": "1"
  }
}

Notification

Asynchronous operations cannot be performed immediately. You can monitor the progress and result of such operations via notifications. Synchronous requests do not use notifications.

If the WAPI is unable to complete the operation immediately, it will return in the response Request pending (1001). When the operation is complete (for more complicated actions of individual steps), it creates a notification that is similar to a classic response. You can assign the notification to the corresponding request using the clTRID or svTRID parameters.

Notification data is always in UTF-8 encoding.

You can receive notifications in the following ways (depending on your settings when activating):

  • Through the POLL front.
  • By sending to the e-mail address provided.
  • Via HTTP (or HTTPS) protocol to the URL address you specify using the POST method in the request parameter. An HTTP response with a return code of 200 is considered a correct delivery. If the delivery fails, our system will try to deliver again at intervals of several minutes.

For example, a sample JSON notification looks like this:

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

System notifications

System notifications send information about relevant events, currently only about domain re-registration elsewhere. If you have WAPI enabled on your account, the system sends this information via notification, similar to an asynchronous command.

To set up the protocol in which WAPI sends system notifications, refer to the WAPI Activation chapter in Customer Administration. This option works for notifications sent to an email or URL address. In the case of a download from a POLL queue, the response is in the same format as the command.

The structure is the same as for the classic notification, the command is always system-notify. In the data node you will find more detailed information.

Basic commands

The basic commands include ping, ping-async, and the POLL queue poll-req and poll-ack commands.

ping

The ping command is used to test WAPI functionality - for example, login credentials, IP address or code.

The return values are:

  • 1000 - OK

JSON command:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "ping",
    "clTRID": "vlastní id kód"
  }
}

JSON response:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "ping"
  }
}

ping-async

The ping-async command tests the functionality of WAPI notifications.

The return values are:

  • 1000 OK
  • 1001 Waiting for a command

JSON command:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "ping",
    "clTRID": "vlastní id kód"
  }
}

JSON response:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "ping"
  }
}

JSON notifications:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "ping-async",
    "id": "id pro POLL frontu",
    "data": {
      "round": "číslo pokusu",
      "time": "čas",
      "done": 1
    }
  }
}

poll-req and poll-ack

To retrieve notifications from the POLL queue, use a combination of the poll-req and poll-ack commands: 

  1. Use poll-req to download the oldest available notification.
  2. Use the poll-ack command to mark a notification as received and make newer ones available until the queue is exhausted.

The return values for poll-req are:

  • 1000 - notification received
  • 1003 - no unread notifications in the queue
  • 2150 - your account is not set to download notifications from the poll queue

JSON command poll-req:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "poll-req",
    "clTRID": "vlastní id kód"
  }
}

JSON response to poll-req (notification available):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF čas",
        "clTRID": "vlastní id kód nalezeného příkazu",
        "svTRID": "id kód serveru pro nalezený příkaz",
        "command": "název příkazu",
        "id": "id v POLL frontě"
      }
    }
  }
}

JSON response to poll-req (blank notification form):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "poll-req"
  }
}

The poll-ack command is used to enter data (parameters):

  • id - ID of the current POLL notification

The return values for poll-ack are:

  • 1002 - marking the notification as received
  • 2151 - notification not found

JSON command poll-ack:

{
  "request": {
    "user": "váš@login.tld",
    "auth": "vygenerovaný autorizační řetězec",
    "command": "poll-ack",
    "clTRID": "vlastní id kód",
    "data": {
      "id": “ID přijaté POLL notifikace”
    }
  }
}

JSON response to poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF čas",
    "clTRID": "vlastní id kód",
    "svTRID": "id kód serveru",
    "command": "poll-ack"
  }
}

Return codes in responses and notifications help you identify the progress and any WAPI errors.

Basic distribution of return codes:

  • 1xxx - the command went fine.
  • 2xxx - incorrect command (for example, missing input items, their incorrect format or value).
  • 3xxx - target object error - the requested action cannot be performed, the object is not in the correct state (for example, when trying to register an already occupied domain, ...).
  • 4xxx - error during command execution (e.g. unavailability of the domain registry, communication error, etc.).
  • 5xxx - internal error or condition of our system.
  • x0xx, x1xx - general.
  • x2xx - domains.
  • x3xx - DNS.

You can always find the specific responses returned for a given command in the command documentation.

Glossary of terms

  • Asynchronous command: A command executed for a longer period of time, returns only a message about receipt, you follow the progress through notifications.
  • API: Application Programming Interface. An interface that allows you to use your own code to retrieve data or manage a third-party application.
  • Data: the content of some commands specifying detailed settings. The data structure is determined by the specific command.
  • JSON: JavaScript Object Notation. A modern way to communicate with APIs.
  • Return Code: a number identifying the type of WAPI response to the command.
  • Notification: JSON or XML code with messages about the progress of the asynchronous command.
  • Command: WAPI request.
  • Synchronous command: A command executed almost instantaneously. Returns a full response, does not use notifications.
  • System notifications: a special type of notifications about events in the system, WAPI sends them automatically in a set format.
  • UTF-8: Unicode Transformation Format. An extended international character encoding standard supporting a large number of fonts.
  • WAPI: Interface for managing some parts of customer administration (backup account, domains, DNS).
  • XML: eXtended Markup Language. An older way of communicating with APIs.

Did the instructions help you?

Thank you for your feedback!
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Article content
Categories