Antecons API
To register and get API access, please visit www.antecons.net.
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.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:
Pretty JSON
For testing purposes, you can prettify the JSON output using the query string parameter 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:
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).