Connecting

Rate limiting

We rate limit the API using a leaky bucket implementation. This allows for 2 GET request or 1 non GET (e.g. PUT/POST/DELETE) within a 1 second period. You can inspect the response headers for details on remaining capacity if needed. When the usage does exceed the capacity on the account, a 429 (Too Many Requests) response code is returned.

We recommend using an outbound rate limiter in your code to handle the leaky bucket implementation. For example, in Node.js you could use the Bottleneck library (https://www.npmjs.com/package/bottleneck).

import Bottleneck from 'bottleneck';
import request from 'request-promise-native';
// Allow up to 2 calls per second
const limiter = new Bottleneck({
    maxConcurrent: 2,
    minTime: 1000,
});
// Throttle the requests
const throttle = async (...params) => limiter.schedule(() => request(...params));
// Resources to fetch, this is above the 2 allowed per second
const resources = ['sales', 'purchases', 'dropship-providers'];
const options = {
    method: 'GET',
    headers: {
        Authorization: `Bearer ${process.env.TOKEN}`,
    },
    json: true,
};
const go = async () => {
    // Fetch all requests without errors
    const responses = await Promise.all(
        resources.map(resource => throttle({
            uri: `https://api.jetti.io/api/${resource}.json`,
            ...options,
        })),
    );
    /* eslint no-console: 0 */
    console.log(`Fetched ${responses.length} resources`, responses);
};
go();

Querying

You can do complex filtering if needed with the API requests. The filtering parameters should be included within a where object in the GET parameters. As a basic example, if you wanted to filter based upon the ID of a parent item (e.g. to filter the list of purchases by the dropship provider ID):

{
    "where": {
        "dropshipProviderId": 1234,
    }
}

You'll need to encode the above object into the URL parameters. For example, the above request would look like:

https://api.jetti.io/api/purchases.json?where%5BdropshipProviderId%5D=1234

You can specify more complex filtering if needed. The current methods are detailed below. Adding multiple parameters act as an AND query, in that all conditions in the where query must be met in order for the data to appear.

import request from 'request-promise-native';
const go = async () => {
    const response = await request.get('https://api.jetti.io/api/purchases.json', {
        headers: {
            Authorization: `Bearer ${process.env.TOKEN}`,
        },
        json: true,
        qs: {
            where: {
                createdAt: {
                    // $lte looks for values less or equal to the supplied value.
                    // Works on dates and numerical fields.
                    $lte: '2019-01-01T00:00:00Z',
                    // $gte looks for values greater than or equal to the supplied value.
                    // Works on dates and numerical fields.
                    $gte: '2018-01-01T00:00:00Z',
                },
                // $in looks for values within an array. Works on most field types
                // For example, you can look within a set up ENUM values, strings etc.
                purchaseType: {
                    $in: ['dropship', 'automated_dropship', 'adjusted_dropship'],
                },
            },
        },
    });
    /* eslint no-console: 0 */
    console.log('Fetched  resource', response);
};
go();

Ordering and pagination

Data is limited to 50 items. However, some endpoints may by default increase or decrease this number. You can specify your own limit if need. You can also specify order and pages numbers if you need to sort and paginate the data.

import request from 'request-promise-native';
const go = async () => {
    const response = await request.get('https://api.jetti.io/api/purchases.json', {
        headers: {
            Authorization: `Bearer ${process.env.TOKEN}`,
        },
        json: true,
        qs: {
            limit: 100,
            from: 2,
            order: {
                // Name of the attribute to order by
                attribute: 'dateOrdered',
                // If null values are possible, include those first (true) or last (false)
                nullsFirst: true,
                // Set false to order ascending
                descending: true,
            },
        },
    });
    /* eslint no-console: 0 */
    console.log('Fetched  resource', response);
};
go();

Includes and attributes

We recommend only requesting the fields needed when pulling data from the API to reduce response times and decrease load. You can do this by specifying an attributes parameter.

For includes, an array of models to include can be specified in the includes attribute. In this array you can filter to limit attributes within the included model.

import request from 'request-promise-native';
const go = async () => {
    const response = await request.get('https://api.jetti.io/api/purchases.json', {
        headers: {
            Authorization: `Bearer ${process.env.TOKEN}`,
        },
        json: true,
        qs: {
            // Only return the dropship provider ID within the base model
            attributes: ['id', 'dropshipProviderId'],
            // Include the associated purchase object, but only nclude the ID
            // attribute
            include: [{
                model: 'Purchase',
                attributes: ['id'],
            }],
        },
    });
    /* eslint no-console: 0 */
    console.log('Fetched  resource', response);
};
go();

Aggregation

It's possible to perform aggregation queries against the API for counts, sums etc of items. Below is an example of an API request to count the number of purchases for a given dropshipProviderId.

import request from 'request-promise-native';
const go = async () => {
    const response = await request.get('https://api.jetti.io/api/purchases/count.json', {
        headers: {
            Authorization: `Bearer ${process.env.TOKEN}`,
        },
        json: true,
        qs: {
           where: {
             dropshipProviderId: 123,
           },
        },
    });
    /* eslint no-console: 0 */
    console.log('Fetched  resource', response);
    // { "count": 123 }
}
};
go();