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 to use the WEDOS Credit Account, from which the system deducts payments for registrations, renewals, transfers, and other charged fees.

WAPI currently allows management of:

WAPI limits

As protection against abuse, WAPI applies the following limits:

  • Via one user account, you can send a maximum of 1000 requests per hour. This applies to all requests of all types; once 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 sending of invalid requests (authentication 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 result, after more than 10 invalid requests, in IP address blocking 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 through WAPI are synchronous – you send a command and, usually within a few seconds, you learn the result. 

Some operations are asynchronous, meaning that processing such a command can take a very long time (even hours or days). WAPI therefore does not return the final result, but only information about the acceptance of the command. 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 the Set button.
Open WAPI settings
Sample WAPI activation
Sample WAPI activation

All settings entered during activation can later be changed in the same way. By deleting the contents of the Allowed IP addresses field, you deactivate WAPI.

Communication and authentication

Communication with the WAPI interface takes place over the HTTPS protocol. Data is transferred using the POST method in the request parameter in XML or JSON format. The basic structure 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

A 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 WAPI command itself. Required parameter.
  • clTRID: Request ID, optional parameter. You can insert any string as an identifier into this element, which WAPI will return in the response.
  • data: Data part of the command. Optional parameter.
  • test: Test mode flag, optional parameter. If you insert a test element with value 1 into 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 does 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 want to test the request only, optional)"
  }
}

A complete example of use in PHP (data format JSON) can 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 want to test the request only)'
  ]
];

$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

A response consists of the following data:

  • code: Return value of the command. More information can be found in the Return codes section.
  • result: Text description of the return code.
  • timestamp: Time of command execution 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: Included in the response for commands that also contain this flag.

A sample response in JSON format looks like this, for example:

{
  "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 completed immediately. The progress and result of such operations can be tracked through notifications. Synchronous requests do not use notifications.

If WAPI cannot complete an operation immediately, it returns Request pending (1001) in the response. After the operation is completed (for more complicated actions, after individual steps), it creates a notification that is analogous to a classic response. You can assign the notification to the corresponding request according to 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 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 successful delivery. If delivery fails, our system will attempt delivery again at intervals of a few minutes.

A sample notification in JSON format looks like this, for example:

{
  "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 provider. If WAPI is active for your account, the system sends such information as a notification, similarly to 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 by e-mail or to 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 classic notification; the command is always system-notify. More detailed information can then be found in the data node.

Basic commands

Basic commands include ping, ping-async, and POLL queue commands poll-req and poll-ack.

ping

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

The 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.

The return values are:

  • 1000 OK
  • 1001 Waiting for command

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 retrieve 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 and thereby make newer ones available until the queue is exhausted.

The 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 found command",
        "svTRID": "server id code for found command",
        "command": "command name",
        "id": "id in POLL queue"
      }
    }
  }
}

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

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

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

  • id – ID of the current POLL notification

The 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 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"
  }
}

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

Basic division of return codes:

  • 1xxx – the command was processed 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 trying to register an already occupied domain, ...).
  • 4xxx – error while executing the command (e.g. domain registry unavailable, 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

  • Asynchronous command: A command executed for a longer time; it returns only a message about acceptance, and you track 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 determined by the specific command.
  • JSON: JavaScript Object Notation. A modern way of communicating with an API.
  • Return code: A number identifying the type of WAPI response to a command.
  • Notification: 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 notifications about events in the system; WAPI sends them automatically in the set format.
  • UTF-8: Unicode Transformation Format. A widely used international character encoding standard supporting a large number of scripts.
  • 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 an API.
Article Contents
Categories