Antecons API

To register and get API access, please visit www.antecons.net.

If you want to see how the API can be used for product recommendations on a webshop, take a look at the demo shop.

Introduction

The Antecons API is designed based on the principles of REST. Data is represented as resources and interactions with resources use standard HTTP verbs such as GET and POST.

For example, this webpage represents the home resource and your browser used a GET request to fetch it. As you can see, it is just a normal webpage with HTML because the Antecons API is available in both an HTML and JSON version.

For most interactions with the API, the JSON version should be used. The HTML version is mostly for browsing, to get a feel for the API and for documentation. More info about HTML/JSON in the content types section.

If you want to start browsing the API immediately, go to the navigation links at bottom of this page and have your API key and secret ready. Otherwise, read on.

Getting started

To access the API, you need an API key and an API secret. These are available immediately after registering for Antecons.

Integrating Antecons recommendations with your system usually involves both sending and fetching data to and from the API. The typical steps that are needed for integrating with Antecons are:

Register an account with Antecons and take notice of the API key and API secret.
Add antecons.js to your shop/website pages.
Start sending data when certain events occur. For example, every time an order is placed on your shop.
Fetch and show recommendations.

Demonstration

To help you get an idea about how to integrate Antecons, we have created a simple demo shop . The demo shop shows how Antecons can be used to provide product recommendations on a webshop and it is open source.

Client libraries

In order to make it easier to integrate Antecons, we plan on making pre-build client libraries available for different programming languages. Currently, there is an early version available for PHP:

Antecons PHP library

Antecons.js

In order for Antecons to collect click statistics and visitor information, it is a good idea to add antecons.js to all your webpages. This improves the recommendations from Antecons and it provides usage statistics so you can see how Antecons is doing.

To start using antecons.js, include the script and initialization code right before the </body> tag:

...
<script src="https://api.antecons.net/js/antecons.js"></script>
<script>
    Antecons.init({ apiKey: 'soeRYhkQgxC', datasource: 'demo' });
</script>
</body>
...

This makes an Antecons JavaScript object globally available on your webpage.

Initialization

Before you can use the Antecons object, it needs to be initialized with some settings and optional information about the current page with the init function.

init takes a single JavaScript object as argument and it can contain the following keys:

Key	Type	Required	Description
apiKey	String	Yes	Your API key, for example `'soeRYhkQgxC'`.
datasource	String	Yes	Indicates what Antecons datasource the data for the current page is organized under, for example `'demo'`.
product	Object	No*	The product that the current page represents. For example, this could be a physical product or an article and represented as: `{product_id: '1111', title: 'Soccer ball 2014'}`.
user	Object	No	The user that is currently viewing your page, for example: `{user_id: '4444', name: 'Bob The Builder'}`.
track	Boolean	No	Indicates whether page and click tracking is enabled for Antecons. Default is `true`.

* Page tracking does not work without at least a product ID. If no product is present, Antecons does not know what to track.

Here is a full example of init:

Antecons.init({
    apiKey: 'soeRYhkQgxC',
    datasource: 'demo',
    product: {
        product_id: '1111',
        title: 'Soccer ball 2014',
        type: 'ball',
        categories: [
            { category_id: '2222', title: 'Soccer balls' },
            { category_id: '3333', title: 'Products from 2014' }
        ]
    },
    user: {
        user_id: '4444',
        name: 'Bob The Builder'
    },
    track: true
});

The example above shows all the settings that Antecons currently understands. Most of the information about a product and user are optional (such as title and type).

The example below shows a smaller init that includes just enough information for product tracking to work:

Antecons.init({
    apiKey: 'soeRYhkQgxC',
    datasource: 'demo',
    product: { product_id: '1111'}
});

Click tracking

If you want to enable click tracking, you need to add a data-ac-track attribute to any link or element, that you want to track when a user clicks on the element.

For example, if Antecons recommends the product with product ID "1111" and you show this recommendation as a link, antecons.js will automatically track a click if you add the data-ac-track attribute to the link like this:

<a href="/product/soccer-ball-2014" data-ac-track="1111">Soccer ball 2014</a>

Security

There are two important security consideration to notice when using the API:

Use HTTPS for all requests to the API.
Protect your API secret. Never expose the secret on a webpage (for example using JavaScript).

The API key and secret can be reset at any time if needed.

Authentication

Most requests to the API require authentication. The only exception is the home ressource that you are looking at right now.

The API uses Basic Authentication. Basic authentication is easy to use but it should only be used for server-to-server communication. You should never use basic authentication via JavaScript on a public webpage because this would expose your API secret to anyone visiting the webpage.

Example request with basic authentication using cURL:

curl https://api.antecons.net/home -u hej:farvel

(API key: "hej", API secret: "farvel")

Content types

All resources are available in either JSON or HTML format.

To specify the content type of a resource you are interested in, you have two options:

Use an Accept header:
- Accept: application/json
- Accept: text/html
Use an extension for the URL of the resource:
- /home.json
- /home.html

Pretty JSON

For testing purposes, you can prettify the JSON output using the query string parameter pretty=1:

/home.json?pretty=1

Resources and links

Every JSON resource is described by a JSON Schema. The schema is referenced in a HTTP Link header for every response from the JSON API.

For example, if you access the JSON version of the home resource, the response will have a link header that points to the home schema:

Link: </schemas/home>; rel="describedby"

Central API schema

All the JSON API resources and links are described in a central API schema found at:

https://api.antecons.net/api

Links between resources

Most resources have a number of navigation options. For the HTML API, these are just shown as standard links and forms.

For the JSON API, the underlying schema of the resource determines what navigation options are available for the given resource. This way of defining links follows the JSON Hyper-Schema specification. An example is given below.

Schema example

As a quick introduction to JSON Schema and Hyper-Schema, here is the full JSON Schema for the home resource:

{
    "title": "API home",
    "description": "The main entry point for the Antecons API",
    "$schema": "http://json-schema.org/draft-04/hyper-schema#",
    "type": "object",
    "properties": {
        "info": {
            "description": "Provides general information about the API",
            "type": "string"
        },
        "version": {
            "description": "The version number of the API",
            "type": "string"
        }
    },
    "links": [
        {
            "rel": "self",
            "href": "/home"
        },
        {
            "rel": "datasources",
            "href": "/datasource"
        }
    ]
}

The schema gives a title and description to the resource.

The $schema keyword is a reference to another JSON schema that describes this schema. In most cases, this will be the JSON Hyper-Schema.

The type and properties keywords describe the type and content of the resource. For the home resource, we can see that it is a JSON object with two properties, info and version, and they are both strings.

Finally, the links keyword specifies the navigation options that are available from the resource. For the home resource, there are two link relations: A relation to itself and to datasources.

Where to go from here?

Below are some links to resources you can get to from the home resource (requires authentication).

Datasources