Web Services Overview

TLS 1.0/1.1 deprecated!

We provide wrappers in a number of high-level languages to make writing your applications easier. We recommend using these for all but the most basic testing.

Access
Authorisation
Time units
Cost units
Web service errors
TLS

Access

All web services are available for use through any HTTP client, such as cURL for the command line, or any language specific library that can perform HTTP Requests, such as Requests for python or Apache HttpClient for Java.

Support for TLS 1.0/1.1 has been deprecated. See the TLS section for details.

All services are served from the generic URL https://ws.aculabcloud.net. Each cloud region also serves all services from cloud-specific URLs of the form https://ws-[cloudID].aculabcloud.net. For example, https://ws-1-2-0.aculabcloud.net can be used for accounts in the USA-East region. The latency when using the cloud-specific URLs will be slightly lower than for the generic URL.

The service actions make up the path of the final URL. i.e. https://ws.aculabcloud.net/file_list for the File List service.

Authorisation

When accessing a web service using an HTTP client, the following basic authentication is required unless otherwise stated in the documentation for that service - specifically the Starting Outbound Services, Managing Outbound Service Queues, Voice Biometrics Users APIs.

The format for the username and password is as follows:

Username	:	cloudID/username (e.g. 1-2-0/user@example.com)
Password	:	Your API Access Key

For example:

$ curl --user 1-2-0/user@example.com:WzyPvLMYBUMvFOgXj3S7fg https://ws.aculabcloud.net/file_list?filetype=media

Time Units

Several services return time properties. Unless otherwise documented these are specified in seconds since the Unix epoch UTC, 1st January 1970 00:00, where UTC is the Coordinated Universal Time.

Cost Units

All costs are returned in US dollars and cents.

Web Service Errors

Many of the web services will return HTTP standard response codes (e.g. 404 Not Found) if the service cannot carry out the requested action. In addition these web services may return a four digit error code that provide specific detail of the error encountered. These are described here.

TLS

TLS 1.2 and 1.3 are supported on all web services. However, for security reasons, TLS 1.0 and 1.1 are deprecated on Aculab Cloud and support for these protocols will be removed in August 2020. Those interfacing directly with these web services need to remove any TLS 1.0/1.1 dependencies and disable them at the Operating System level where possible. Users of our high-level language wrappers may need to upgrade to a newer version to ensure continued operation and/or move onto a later language environment.

How this is achieved depends on the Operating System and language framework being used. You can use the Protocol Check web service to diagnose your connection and check the procotol being used.

We recommend that you target .Net Core or .Net Framework 4.7 or later in your web service client applications and run them on Windows 8/Server 2012 or later. This needs the least configuration to ensure the latest TLS versions are supported.

If you are using the .Net Language Wrappers version 3.3.1 or later then TLS 1.2 should be configured by default.

.NET applications can use the TLS version that the operating system (OS) supports to ensure the strongest security available is used. .Net Framework 4.7 and later Frameworks default to using the OS-selected TLS version. Earlier Frameworks require some configuration.

On Windows, the older operating systems have outdated TLS version defaults. Using Windows 8/Server 2012 or a later Windows OS will guarantee TLS 1.2 as the default security protocol version.

Windows OS	TLS 1.0	TLS 1.1	TLS 1.2
Windows Vista	Default	Not Supported	Not Supported
Windows Server 2008	Default	Disabled*	Disabled*
Windows 7 (WS2008 R2)	Default	Disabled*	Disabled*
Windows 8 (WS2012)	Enabled	Enabled	Default
Windows 8.1 (WS2012 R2)	Enabled	Enabled	Default
Windows 10	Enabled	Enabled	Default
Windows Server 2016	Enabled	Enabled	Default

*TLS 1.1/1.2 can be enabled on Windows Server 2008 via this optional Windows Update package.

On Linux, the TLS version is largely dependent on the version of OpenSSL that is deployed. OpenSSL version 1.0.1 and later versions support TLS 1.2.

This can be achieved as follows:

Perform a thorough code audit to establish that a TLS or SSL version is not being set explicitly.
Configure the .Net Framework to use the OS-specified TLS version. When the OS selects the TLS version it automatically selects the most secure version available and legacy protocol versions are blocked.

Configuring the .Net Framework to allows the OS to select TLS version:

.Net Core
On Windows, .Net Core will use the default security protocol configured in the OS.
On Linux, under Kestrel, the TLS version is determined by the underlying SSL library. OpenSSL 1.0.1 is the first to support TLS 1.2.
.Net Framework 4.7 or later
For HTTP networking, ServicePointManager will use the default security protocol configured in the OS.
Ensure that ServicePointManager.SecurityProtocol is set to the default value SecurityProtocolType.SystemDefault.
.Net Framework 4.6 – 4.6.2
We recommend that you upgrade to .NET Framework 4.7 or later versions.
You may need to set the DontEnableSystemDefaultTlsVersions AppContext switch to false.
.Net Framework 4.5
We recommend that you upgrade to .NET Framework 4.7 or later versions.
Microsoft have published an upgrade process for these earlier frameworks, but they don’t guarantee that applications will continue to work in future without moving to later .Net Frameworks.
You can specify that TLS 1.2 is enabled using:
```
ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;
```

The Java web services download package requires you to have Java 8 (Also known as Java 1.8) installed on your machine. Since its release, Java 8 supports TLS 1.2 and this will be used by default. Currently, Java 8 has no support for TLS 1.3.
Python uses OpenSSL and, for TLS 1.2, OpenSSL needs to be 1.0.1 or higher. The OpenSSL library that Python uses will be one of the following:
- The OpenSSL library that was deployed with the operating system (This is typical of Python distributions on Linux).
- The OpenSSL library that was deployed with the Python distribution you installed (This is typical of Python distributions on Windows).
You can verify the OpenSSL version used by Python with the following command:
```
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
```
When running the command above on Windows using Python 3.8, the output would typically resemble:
```
OpenSSL 1.1.1d  10 Sep 2019
```
For compatibility with TLS v1.2 when running Python2 - OpenSSL v1.0.1+ is required and Python v2.7.9+ is recommended.

For compatibility with TLS v1.2 when running Python3 - OpenSSL v1.0.1+ is required and Python v3.4+ is recommended.

For compatibility with TLS v1.3 when running Python3 - OpenSSL v1.1.1+ is required and Python v3.7+ is recommended.
PHP uses OpenSSL and, for TLS 1.2, OpenSSL needs to be 1.0.1 or higher. For Windows builds from windows.php.net, PHP 5.5 and higher have been built with a suitable OpenSSL library. Most Linux distributions made the change at around the same version of PHP.

You can verify the OpenSSL version used by PHP with the following commands:

On Windows:
```
php.exe -i | find "OpenSSL"
```
On Linux:
```
php -i | grep -i OpenSSL
```
With PHP 7.4.4 on Windows, this outputs:
```
OpenSSL support => enabled
OpenSSL Library Version => OpenSSL 1.1.1d  10 Sep 2019
OpenSSL Header Version => OpenSSL 1.1.1d  10 Sep 2019
OpenSSL support => enabled
```
The "OpenSSL Library Version" is the version used at runtime.

If you need to change the version of PHP you are using, migration guides can be found at https://www.php.net/manual/en/appendices.php