This describes the resources that make up the official Addresscheck REST API v2. If you have any problems or requests, please contact XQueue Support.

Current Version

The current version of the REST API is 2.6.3 and was last updated on February 3rd, 2017. The previous versions (1.x) are deprecated.

Web Service URL Structure

ADC REST API has two roots for its web services:

• the svc root (http://{domain}/svc/...) comprises the full services, protected by authentication, both private and public APIs
• the trial root (http://{domain}/trial/...) is used to offer trial versions of ADC services, for general use without authentication. These services are often limited versions, mostly with quantity restrictions.

Authentication

The public API for customers has several versions and groups:

• resources under …/svc/address deal with the analysis of e-mail addresses
• resources under …/svc/info provide detailed information about various entities (providers, companies, lists …).

These services are rarely called on their own, most often address services reference them in their results and let the user decide whether they need the details or not.

• resources below …/svc/2.0/address deal with the analysis of e-mail addresses
• resources below …/svc/2.0/info provide detailed information about various entities (providers, companies, lists …). These services are rarely called on their own, most often address services reference them in their results, and let the user decide whether they need the details or not.

There are also two groups in the private API for the management of the platform:

• resources below …/svc/service are meant for the variuos management tasks
• resources below …/svc/internal are not part of the regular platform management, these are special purpose services for troubleshooting etc.

The usage of the various services is regulated by user groups.

Public Services

The individual checks that can be used when making an API call are documented under Public Services.

Trial services

Trial serivces are identical to their full counterparts, except for quantity restrictions. Their usage is restricted by certain quotas per day and IP address.

• resources below …/trial/address deal with the analysis of e-mail addresses
• resources below …/trial/info provide detailed information about various entities

Schema

Using the public Addresscheck API is simple. Customers can only use GET requests to receive information about a specific resource. The kind of information and the resource they are seeking is contained in the URL.

To provide a practical example we use famous the command-line utility curl to access the Addresscheck API:

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/foo@bar.com

This call contains all elements that must be present for a successfull call to a protected Addresscheck API:

1. “-G”: we use a GET request, the one that is also used to load web pages. That makes it also possible to access our APIs with a web browser
2. “-basic”: this specifies that the call will use HTTP Basic authentication. HTTP Basic uses a user name/password combination for authentication without encryption.
3. “-u testuser:testuser”: the user name and the password required by HTTP Basic authentication
4. the url “http://…/svc/address/role/foo@bar.com”
   1. svc: we want to access a full, protected service
   2. address: we need information about an e-mail address
   3. role: we want to know about the role aspect of the address
   4. the actual resource, the address foo@bar.com is the last part of the URL

Of course, if we wanted to access a free service, the authentication part wouldn’t be necessary:

curl -G http://testserver.xq/trial/address/role/foo@bar.com

Here we just have to specify the GET operation and the resource.

By default the caller will get an answer in XML format, something like

<roleStatus>
    <result>1</result>
</roleStatus>

The Addresscheck API will answer in XML or JSON. To specify a format the call must include a standard HTTP <pre>Accept</pre> header with application/json for JSON or application/xml for XML. An API call with a JSON specification would look like this:

curl -G -basic -u testuser:testuser -H'Accept: application/json' http://testserver.xq/svc/address/role/foo@bar.com

The only differnce to first call is the Accept header -H’Accept: application/json‘. This header is a standard HTTP header, which is also used by web browsers. In this case the answer would be something like

{"result": 1}

The caller should also check the status code for each API call. Normally successful calls will end with the 200 OK response code. See the individual service descriptions for alternative responses.

Internationalized domains, non-ASCII addresses

If information about international addresses or domains, with non-ASCII characters, is required, the resource, the address must be percent-encoded.

Example: when requesting information about a domain containing a Germ Umlaut like info@blümchen.de, the direct approach:

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/info@blümchen.de

would be illegal. Non-ASCII characters are not allowed in URLs. Instead use percent-encoding to create a valid URL:

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/info@bl%C3%BCmchen.de

Please note that all ADC services except the Quality and the Syntax check expect ASCII addresses as inputs. Please use the mentioned services as entry points to decode possible Unicode addresses, before calling the other services.

Logging & Billing

The system stores no user data except the logging data for API calls that are necessary for billing and troubleshooting. Even this data is only stored temporarily. Since AddressCheck itself has no billing infrastructure, the business even data will be extracted periodically from the system and processed elsewhere.

Addresscheck logs every access to the public APIs as a business event. Every API call is stored with the following data:

• start of API call (timestamp)
• end of API call (timestamp)
• the caller’s IP address
• the account (user name) used; for free services this is noprincipal
• the ID of the API called; see the service descriptions for these IDs
• input data for the API call
• the result of the API call; very long results (>256 bytes) will be shortened

This data serves three major purposes:

1. provides the basis for billing
2. helps with customer complaints; the input and result data can be used to verify customer complaints
3. enables usage reporting and forecasts

The system includes no mechanism for billing or reporting, it just provides the data for these activities. Therefore the business event storage is only a transitory storage. It is expected that the business events are extracted regularily and processed elsewhere.