API Basics¶

Request Authorisation¶

That a service has the right to make an API request is verified using an “authorisation hash”. This value is calculated by hashing the request body (the POST content) and a key specified by the Registration Server.

The hashing algorithm used depends on the Authorisation Method set for the server. This may be one of the following: MD5 (APIChecksumSalt), MD5 (Endpoint specific key) or HMAC-SHA1 (Endpoint specific key), as described here: API Access.

The key can be obtained by clicking on the “Show Key” button of the service in the Admin Console. You need Provider level privileges to view the key.

For MD5-based authorisation methods, the hash value is calculated by concatenating the request body with the key and then calculating the MD5 hash value, and finally converting to lower case.

For example in PHP this would look as follows:

$auth_hash = md5($request_body.$service_key);

(Note: ‘.’ is used for string concatenation in PHP).

For HMAC-SHA1 based methods the has value is calculated in PHP is as follows:

$auth_hash = hash_hmac('sha1', $request_body, $service_key);

In all cases the result is a lower-case hex string. The MD5 result is 32 characters long and HMAC-SHA1 result is 40 characters long. Th Registration Server requires a lower-case hex value. In the case of PHP it is not necessary to use the strtolower() function because the results of these functions is already a lower-case string.

As described above the authorisation hash value must be added to the URL of the API request as a “search arg”. In PHP, for example, as follows:

$api_url = 'https://'.$reg_server_host.'/yvva/api/api.xml'
$api_url = $api_url.'?checksum='.$auth_hash;

IP Address List¶

A service has a number of IP addresses, which are used to verify the origin of a API request.

An IP address must uniquely identify a service, so it is not possible to run multiple services on the same host machine.

A service that accesses the API with an unknown IP address will receive an “Access Denied” error.

Admin Console API Usage¶

The Admin Console also accesses the Registration Server API in order to perform a number of functions. For this reason the AdminConsoleIPAddress global setting must be set to the IP address of the Admin Console.

This will normally be done during Registration Server setup. If, for some reason, this value was not set correctly you will not be able to login to the Admin Console. In this case see Admin console: API error code: -30000, message: Access denied to IP for assistance.

Note that is want to be to manager multiple Providers in the Admin Console then you must set APIAllowSettingDistributor to True as desctribed below.

API Access Rights¶

API access rights are at the level of the Provider. That is, the API user is authorised to perform all action that can be performed by an administrator with Provider level privileges. For this reason, only fully trusted sources should be allowed to access the Admin Console.

When a service accesses the API it is authorised as the Provider to which the service belongs. The authorised Provider can be changed by setting an alternative Provider code in the <distributor> tag.

But this is only permitted when the following applies:

• APIAllowSettingDistributor is set to True and,
• the authorised Provider is the so-called “Default Provider”, which is the Provider that has authority over the entire Registration Server.
• or alternatively, the Provider in the <distributor> tag is “managed by” authorised Provider.

The “managed by” relationship can be set in the Admin Console. This feature allows a group a Providers to be managed by a single “manager Provider”. See “Providers” -> “Provider Settings”.

Usage Considerations¶

If you are accessing the API over a local network or a VPN, you can use plain HTTP. However, when sending the data over an insecure network, you must use HTTPS for security reasons.

If your service provides access to endusers, for example, a Shop Service, then it is the responsibility of your Application Server to ensure that user’s are only able to access there own data.

As mentioned above the authorisation of the API is at the Provider level, and therefore the API does not enforce user level access restrictions.

Standard Parameters¶

The following are standard input parameters to all API calls:

<command>:

This is the name of the API function to be called. This parameter is required.

<requesttime>:

Each request also needs to include a <requesttime> which is the current timestamp converted to an integer (UNIX time).

<distributor>:

This parameter specifies the Provider Code of the Provider that is being accessed. If it is possible that multiple providers access the IP via a single IP address, then this parameter is required (see APIAllowSettingDistributor).

Identifying Users¶

Users are identified in API calls using one of the following tags:

<username>:

The globally unique username of the user. If the name has the format “$<provider-code>-<value”, then it is a so-called “magic username”. Magic usernames are allocated by the Registration Server if no username is given. They are invisible to the enduser (see the registeruser for more details.

<useroremail>:

Use this field to search by username and the registration email address of a user. Functions will first check for the a username. Registration Server versions prior to 3.6.0 allowed an email address to be used as a username. In this case, such users will be found before the actual registration email address is searched. If the value does not contain an “@” character, then an email search is not done.

<reference>:

The external reference of the user. On creation of a user it is optional. If the value us unique it can be used to identify the user. To ensure that the value is unique you must set the Provider setting CLIENT/EXT_USER_REFERENCE_UNIQUE (see EXT_USER_REFERENCE_UNIQUE) to True. A search for this value is always done in combination with the Provider code (<distributor> value).

<authid>:

The external authentication ID. It is used to identify users of an External Authentication Service, such as an LDAP or AD server. The value is unique for the users of a Provider. A search for this value is always done in combination with the Provider code (<distributor> value).

<activationcode>: This option is new in Registration Server 4.0. It can only

be used to identify a user if the user has not yet been activated. If the user has already been activated a -30100 error will be returned.

Note that the activation code may only be used to identify the user in API calls that explicitly allow this (check the call description for details).

Identifying Licenses¶

Licenses are identified in API calls using one of the following tags:

<licensekey>:

The unique license key number generated by the Registration Server.

<licensereference>:

The external reference of the license. This value is optional. If it is unique it can be used to identify the license. To ensure that the value is unique you must set the Provider setting LICENSE/EXT_LICENCE_REF_UNIQUE (see EXT_LICENCE_REF_UNIQUE) to True.

Wrong Apache Configuration¶

Request:

https://<domain>/yvva/api/service.html

Answer:

<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
<p>The requested URL /td2api/api/service.html was not found on this server.</p>
<hr>
<address>Apache/2.4.48 (CentOS) Server Port 443</address>
</body></html>

Application Errors¶

Application errors will return error messages in an XML format like this:

<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
        <regversion></regversion>
        <exception>
                <primarycode></primarycode>
                <secondarycode></secondarycode>
                <message></message>
        </exception>
</teamdrive>

<primarycode> and <secondarycode> (optional) are integer values. <message> is a text.

Error codes regarding the API will start at -30100 (see Error Codes).

General errors with the Yvva Runtime Environment version or database connection are in the range between 0 and -23000.

Programming Errors¶

If a program error occurs, the server will return an error similar to the following one:

<HTML><HEAD><TITLE>Execution Error</TITLE></HEAD><BODY>
<H2>Execution Error</H2><FONT SIZE = +1>An error occured while processing
your request: <BR>Primary error code: <B>-10005</B>, Secondary error code:
<B>0</B><BR><FONT SIZE = 0><H3>"api_init.sys"@client line 7: ';' token
expected in place of 'execute'.</H3></BODY></HTML>

Invalid Requests¶

Invalid requests will return one of the following errors:

<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
        <regversion></regversion>
        <exception>
                <primarycode>-30000</primarycode>
                <secondarycode></secondarycode>
                <message>Access denied</message>
        </exception>
</teamdrive>

<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
        <regversion></regversion>
        <exception>
                <primarycode>-30001</primarycode>
                <secondarycode></secondarycode>
                <message>Invalid Command</message>
        </exception>
</teamdrive>

<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
        <regversion></regversion>
        <exception>
                <primarycode>-30002</primarycode>
                <secondarycode></secondarycode>
                <message>Invalid Request</message>
        </exception>
</teamdrive>

<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
        <regversion></regversion>
        <exception>
                <primarycode>-30003</primarycode>
                <secondarycode></secondarycode>
                <message>Invalid XML</message>
        </exception>
</teamdrive>