WAPI – WEDOS Global

In this article, you will learn:

• How WAPI works
  • Supported services
  • Request restrictions
  • Synchronous and asynchronous requests
• How to activate WAPI in the WEDOS Global admin panel
• How to integrate WAPI to your system
• Basic requests to test WAPI features
• Troubleshooting common issues
• Frequently asked questions

---

WEDOS API (WAPI)

The WEDOS API, WAPI for short, is used to manage WEDOS services directly from your system via requests and responses.

• Communictaion is either synchronous (a response is processed typically within seconds of receiving the request) or asynchronous (some responses may take a longer time; the process is monitored via notifications).
• Data is passed via the HTTPS protocol by the POST method in the request parameter; data encoding is UTF-8.
• Supported formats include both XML and JSON.

Supported Services

WAPI currently supports the following WEDOS Global services:

• WEDOS Protection
• WEDOS DNS and NSSET

Additionally, you can access WEDOS domain registrar services:

• Domains
• Domain contacts
• Credit account

WAPI Restrictions

To protect against misuse, WAPI applies the following restrictions:

• One user account can send a maximum of 1000 requests per hour. This applies to all types of requests. When this limit is reached, WAPI rejects further requests until the timeout 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 requests.
• Repeated invalid requests (authorization failure, access from an unauthorized IP address, incorrect input, missing or incorrect parameters, unknown commands, commands resulting in any error, or any request beyond other restrictions) will cause the IP address to be blocked for 1 minute for each invalid request in excess of 10. With each additional invalid request, the system increases the blocking time.

Synchronous and asynchronous requests

Most of the requests executed via WAPI are synchronous – you send the request and you usually get the result within a few seconds.

Some requests are asynchronous – processing such requests can take a very long time (even hours or days). In such cases, WAPI doesn’t return the final result, but only information about receiving the request. The system then sends you information about the progress and the final result in the form of notifications.

---

Activate WAPI

Before you can start using WAPI, you need to activate it. Follow these steps:

1. Log into the WEDOS Global admin panel ⧉.
2. In the left bar, select WAPI.
3. In the WAPI Setup form, enter the following and confirm using the Set button:
   • Allowed IPs: A comma-separated list of IP addresses (both IPv4 and IPv6) from which your system connects to WAPI.
   • Notification Method: A method of receiving notifications about the progress of asynchronous requests. For more information, see the WAPI Manual ⧉.
   • Preferred Protocol: This setting only applies to system notifications. Responses use the same format as requests. For more information, see the WAPI Manual ⧉.
4. In the Password Settings form, enter the WAPI password (twice to confirm it) and click the Set button.

The settings will take effect within 30 minutes.

---

Integrate WAPI into Your System

To integrate WAPI into your system once it’s been activated, you need to:

• Set up a script to connect to the API
• Send a request
• Receive and process a response
• Receive and process a notification

Connect to WAPI

To connect your system to WAPI, you will need:

• Your WEDOS login email and WAPI password
• The WAPI URL (depends on format):
  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

WAPI takes a single authentication string, which is a sha1 hash of a string composed of the username, the sha1 hash of the WAPI password and the current time (00-23). The time zone is Europe/Prague (UTC+1 CET, or UTC+2 CET with DST adjustment). See code below for a specific example.

The following template demonstrates connecting to WAPI using a PHP script:

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

WAPI Request

A WAPI request request consists of the following data:

• test: Test mode flag, optional. If you include a test element with a value of 1 in the request, WAPI will only check the command, but not make any changes in the system.
• user: Your WEDOS customer account login (email), required.
• auth: Authorization string, required. This is a sha1 hash of a string composed of the username, the sha1 hash of the WAPI password and the current time (00-23). The time zone is Europe/Prague (UTC+1 CET, or UTC+2 CET with DST adjustment). See code below for a specific example.
• command: The actual WAPI request. Required.
• clTRID: Request ID, optional. You can put any string in this element as an identifier that WAPI will return in the response.
• data: The data part of the request. Optional.

The following is a template JSON request:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      request data
    }
    "clTRID": "request-id (optional)",
  }
}

WAPI Response

The response consists of the following data:

• code: The return value for the given request. You can find more information in about these codes in specific command documentation.
• result: Return code description.
• timestamp: Command execution time in UNIX format.
• clTRID: Client’s request identifier.
• svTRID: Server’s request identifier.
• command: WAPI request.
• data: Return data. None if the request fails.
• test: Included with responses for test requests.

The following is a template JSON response:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notifications

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

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

Notification data is always encoded in UTF-8.

You can receive notifications in the following ways (according to the settings):

• Using the POLL queue.
• Send to specified email address.
• Via HTTP (or HTTPS) protocol to the URL address specified by you using the POST method in the request parameter. An HTTP response with a return code of 200 is considered a success. If delivery fails, the system will attempt to deliver the notification againat several-minute intervals.

The following is a template JSON notification:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Basic Requests

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

ping

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

The return values are:

• 1000 – OK

JSON request template:

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

JSON response template:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

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

The return values are:

• 1000 – OK
• 1001 – Waiting for request

JSON request template:

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

JSON response template:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

JSON notification template:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req and poll-ack

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

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

The return values for poll-req are:

• 1000 – notification received
• 1003 – no unread notification in queue
• 2150 – poll queue notifications disabled for this account

JSON poll-req request template:

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

JSON poll-req response template (notification available):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req response template (empty notification queue):

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

Include the following parameters in the poll-ack request:

• id – current poll notification ID

The return values for poll-ack are:

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

JSON poll-ack request:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack response:

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

---

Troubleshooting Common Issues

Common issues with WAPI include:

• Failing to authenticate requests

---

FAQ