API Documentation

Using the 24Nettbutikk API

The API is the primay way to get data out of a 24Nettbutikk webshop. There are 3 models currently available through the API: orders, products and customers.

Sandbox

There's a playground setup here: http://api-demo.24nb.no/api/v1?access_token=193fe10a5d82db1ade9f90845f6fca84756c393b JSFiddle: http://jsfiddle.net/wy1tdfeb/21/

Basics

Requests need to be authenticated with a token, and everything is either JSON or JSONP.

Blank fields are included as null instead of being omitted, except on pagination links.

All modified_on attributes are returned in ISO 9075 format in the timezone of the server:

YYYY-MM-DD HH:MM:SS

The format used for time based pagination is unix timestamps. Time based pagination filters on the modified_on attribute.

Authentication

Each webshop is automatically issued an API token. Retrieving it is done through the admin panel: /admin/index.php?nr=103 If a token needs to be regenerated, follow these steps:

1. Delete the token from the api_tokens table.
2. Visit /admin/index.php?nr=103 and a newly generated token is displayed.

Authentication

The API supports Basic Authentication as defined in RFC2617. We may consider adding authentication via Username and Password, but for the time being only OAuth Tokens are allowed.

Basic Authentication

Provide the token as the username and provide a blank password or a password of x-oauth-basic. If you're accessing the API via cURL, replace <token> with your OAuth token in the following command:

$ curl -u <token>:x-oauth-basic 'https://example.com/api/v1/orders'

OAuth2 Token (sent as a parameter)

$ curl 'https://example.com/api/v1/orders?access_token=<token>'

Parameters

Many API methods take optional parameters. Parameters not specified as a segment in the path can be passed as an HTTP query string parameter. For the time being it's just one argument, callback used together with JSONP:

$ curl -i 'https://example.com/api/v1/orders/0/100/1415790957?callback=console.log'

In this example, the '0', '100' and '1415790957' values are provided for the :offset, :limit and :since parameters in the path while :callback is passed in the query string.

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the API supports:

$ curl 'https://example.com/api/v1'

Name	Description
customers	Registered customers
orders	Orders, purchases everything related
products	The webshop’s products

Pagination

Requests which return multiple items will be paginated to 100 items by default. You can specify further items with the :limit parameter.

$ curl 'https://example.com/api/v1/orders/1000/'

Note that page numbering is offset based. The first parameter is :limit and the second is :offset. If you omit :offset then the default value is 0. In the case above the first 1000 items will be fetched. The next page would be:

$ curl 'https://example.com/api/v1/orders/1000/1000/'

Example JS Fiddle with how offset pagination works: http://jsfiddle.net/wy1tdfeb/21/

Every request return queried data in the data property. Paginated requests contain a paging property with pagination links.

Example request to http://example.com/api/v1/orders/100/100 would return this response:

{
    "data": [],
    "paging": {
        "prev": "http://example.com/api/v1/orders/100/0",
        "next": "http://example.com/api/v1/orders/100/200"
    }
}

Additional information on paging links

Pagination links include :offset and :limit in every link, using the default values of 0 and 100 if the parameters aren't defined. They will also contain :until, :since, :access_token and :callback if defined in the request. Offset based pagination returns oldest items first. This ensures that data added after a pagination session begins won't be missed. Time based navigation is sorted by the modified_on timestamp, assuring that all data is up to date when the pagination session completes. Items may appear multiple times during a pagination session if modified.

Paging: Prev

• The property prev will not be set if :offset equals zero, or if there table is empty.
• The :offset parameter in the prev link stops incrementing when the current :offset is greater than the total number of rows. This is to ensure the prev link will never return zero items.

Paging: Next

• The property next only exists if there are more items.

Time based pagination

Requires the :since parameter in the url, formated as a unix timestamp, in addition to :limit and :offset.

$ curl 'https://example.com/api/v1/orders/100/0/1415887613'

This example will select the 100 oldest items since Thu, 13 Nov 2014 12:06:53 +00:00.

Optionally define :until to select items that were modified between a specified range, also a unix timestamp.

$ curl 'https://example.com/api/v1/orders/100/0/1415887613/1415887613'

This example selects the 100 oldest items between Thu, 13 Nov 2014 12:06:53 +00:00 and Thu, 13 Nov 2014 14:06:53 +00:00

Example request to http://example.com/api/v1/orders/100/100/1415887613 would return this response:

{
    "data": [],
    "paging": {
        "prev": "http://example.com/api/v1/orders/100/0/1415887613",
        "next": "http://example.com/api/v1/orders/100/200/1415887613"
    }
}

HEAD requests

A HEAD request to root endpoints will return the header Last-Modified with a timestamp for when a table was last modified. For performance reasons it is recommended to ping HEAD requests instead of GET to know when data has been modified since last scan.

$ curl 'https://example.com/api/v1/orders/' -I

Expanded information on API end-points

This will be generated in separate files. Each file will contain the following sections:

1. Information on the request route and available parameters.
2. A list over fields, explaining each field.
3. A list over edge points, if any (order_lines on orders is an "edge point")