CS · EN

WAPI - Manual

In this article, you will learn:

WEDOS API

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

The condition for using the interface is the use of a Credit Account - Manual, from which the system deducts payments for registrations, renewals, transfers, and other charged fees.

WAPI currently allows management of:

WAPI limitations

As protection against misuse, WAPI applies these limitations:

  • You can send a maximum of 1000 requests per hour through one user account. This applies to all requests of all types; when this limit is reached, WAPI rejects further requests until the time limit expires.
  • One user account may submit a maximum of 100 domain availability requests per hour. This applies to the domain-check, domain-create and domain-transfer-check commands.
  • Repeated submission of invalid requests (authorization failure, access from an unauthorized IP address, incorrect input, missing or incorrect parameters, unknown command, commands ending with any error, or any request beyond the other limits) will, after exceeding 10 invalid requests, result in blocking the IP address for 1 minute for each invalid request. With each additional incorrect request, the system extends the blocking time.

Synchronous and asynchronous operations

Most commands performed via WAPI are synchronous – you send a command and usually learn the result within a few seconds. 

Some operations are asynchronous, meaning processing such a command may take a very long time (even hours or days). WAPI therefore does not return the final result, but only information that the command was accepted. Information about progress and the final result is then sent to you by the system in the form of notifications.

Activating WAPI in the 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. In the top menu, select My account Customer.
  3. In the left menu, select WAPI interface.
  4. Set the allowed IP addresses, notification method, preferred protocol, and password.
  5. Confirm the settings with Set.
Open WAPI settings
Sample WAPI activation
Sample WAPI activation

You can later change all the settings entered during activation in the same way. Deleting the contents of the Allowed IP addresses field will deactivate WAPI.

Communication and authentication

Communication with the WAPI interface takes place over the HTTPS protocol. Data is passed using the POST method in the request parameter in XML or JSON format. The basic form of the command and response is the same for all commands. Data encoding is UTF-8.

Interface URLs:

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

Request structure

The request consists of the following data:

  • user: Username (e-mail) of your customer account, required parameter.
  • auth: Authorization string, required parameter. This is a sha1 hash of a string composed of the username, the sha1 hash of the WAPI password, and the current hour (00-23). The time zone is Europe/Prague (winter time UTC+1 CET, summer time UTC+2 CEST). See the code below for a specific example.
  • command: The actual WAPI command. Required parameter.
  • clTRID: Request ID, optional parameter. You may insert any string into this element as an identifier that WAPI returns in the response.
  • data: Data part of the command. Optional parameter.
  • test: Test mode flag, optional parameter. If you include a test element with value 1 in the command, WAPI will only check your command and will not make any changes.

When communicating with WAPI, provide the WAPI password. The customer account password will not work.

The request template (JSON) is therefore:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "authorization string",
    "command": "request name",
    "data":
    {
      request data
    }
    "clTRID": "request identifier (optional)",
    "test": "1 (if you only want to test the request, optional)"
  }
}

A complete example of use in PHP (data format JSON) may then be:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your WAPI password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data field'],
  'clTRID' => 'request identifier (optional)',
  'test' => '1 (if you only want to test the request)'
  ]
];

$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=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Response structure

The response consists of the following data:

  • code: Return value of the command. More information can be found in the Return codes chapter.
  • result: Text description of the return code.
  • timestamp: Time the command was executed in UNIX format.
  • clTRID: Command identifier on the client side.
  • svTRID: Command identifier on the server side.
  • command: WAPI command.
  • data: Returned values. If the command fails, no data is returned.
  • test: Included in the response to commands that also contain this flag.

A sample response in JSON format 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"
  }
}

Notifications

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

If WAPI cannot complete an operation immediately, it returns Request pending (1001) in the response. Once the operation is completed (for more complex actions, individual steps), it creates a notification, which is equivalent to a standard response. You can assign the notification to the corresponding request using the clTRID or svTRID parameters.

Notification data is always encoded in UTF-8.

You can obtain notifications in the following ways (depending on the settings made during activation):

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

A sample notification in JSON format 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 transfer to another registrar. If your account has WAPI activated, the system sends such information through a notification in the same way as for an asynchronous command.

Set the protocol in which WAPI sends system notifications according to the chapter Activating WAPI in the customer administration. This option works for notifications sent to e-mail or a URL address. In the case of retrieval from the POLL queue, the response is in the same form as the command.

The structure is the same as for a standard notification; the command is always system-notify. More detailed information can be found in the data node.

Basic commands

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

ping

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

Return values are:

  • 1000 – OK

JSON command:

{
  "request": {
    "user": "your@login.tld",
    "auth": "generated authorization string",
    "command": "ping",
    "clTRID": "custom id code"
  }
}

JSON response:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTC time",
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "ping"
  }
}

ping-async

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

Return values are:

  • 1000 OK
  • 1001 Request pending

JSON command:

{
  "request": {
    "user": "your@login.tld",
    "auth": "generated authorization string",
    "command": "ping",
    "clTRID": "custom id code"
  }
}

JSON response:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTC time",
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "ping"
  }
}

JSON notification:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTC time",
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "ping-async",
    "id": "id for POLL queue",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req and poll-ack

You obtain notifications from the POLL queue by combining the poll-req and poll-ack commands: 

  1. Use poll-req to download the oldest available notification.
  2. Use poll-ack to mark the notification as received, thereby making newer ones available until the queue is exhausted.

Return values for poll-req are:

  • 1000 – notification obtained
  • 1003 – there is no unread notification in the queue
  • 2150 – your account is not set up to download notifications from the poll queue

JSON command poll-req:

{
  "request": {
    "user": "your@login.tld",
    "auth": "generated authorization string",
    "command": "poll-req",
    "clTRID": "custom id code"
  }
}

JSON response to poll-req (notification available):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTC time",
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTC time",
        "clTRID": "custom id code of the found command",
        "svTRID": "server id code for the found command",
        "command": "command name",
        "id": "ID in the POLL queue"
      }
    }
  }
}

JSON response to poll-req (empty notifications form):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "poll-req"
  }
}

For the poll-ack command, you provide data (parameters):

  • id – ID of the current POLL notification

Return values for poll-ack are:

  • 1002 – notification marked as received
  • 2151 – notification not found

JSON command poll-ack:

{
  "request": {
    "user": "your@login.tld",
    "auth": "generated authorization string",
    "command": "poll-ack",
    "clTRID": "custom id code",
    "data": {
      "id": “ID of the received POLL notification”
    }
  }
}

JSON response to poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTC time",
    "clTRID": "custom id code",
    "svTRID": "server id code",
    "command": "poll-ack"
  }
}

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

Basic division of return codes:

  • 1xxx – the command completed successfully.
  • 2xxx – invalid command (for example, missing input items, 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 attempting to register an already occupied domain, …).
  • 4xxx – error while executing the command (e.g. unavailability of the domain registry, communication error, etc.).
  • 5xxx – internal error or state of our system.
  • x0xx, x1xx – general.
  • x2xx – domains.
  • x3xx – DNS.

The specific responses returned for a given command can always be found in the command documentation.

Glossary of terms

  • Asynchronous command: A command executed over a longer period of time; it returns only a message about acceptance, and you follow the further progress through notifications.
  • API: Application Programming Interface. An interface that allows you to use your own code to obtain data or manage a third-party application.
  • Data: The content of some commands specifying detailed settings. The data structure is defined by the specific command.
  • JSON: JavaScript Object Notation. A modern way of communicating with APIs.
  • Return code: A number identifying the type of WAPI response to a command.
  • Notification: A JSON or XML code with messages about the progress of an asynchronous command.
  • Command: A request to WAPI.
  • Synchronous command: A command executed practically immediately. It returns a full response and does not use notifications.
  • System notifications: A special type of notification about events in the system; WAPI sends them automatically in the configured format.
  • UTF-8: Unicode Transformation Format. A widely used international character encoding standard supporting a large number of writing systems.
  • WAPI: An interface for managing some parts of the customer administration (credit account, domains, DNS).
  • XML: eXtended Markup Language. An older way of communicating with APIs.
Article Contents
Categories