General concepts

API location

The API is available on the following URL: https://api.farmaframe.be

For backwards compatibility reasons most of the API is also available over an unsecured HTTP channel ( http://api.farmaframe.be). We strongly advise you to only use the HTTPS channel. If you do decide to use an unsecured connection, please note that the following features will not be available:

Authentication

Most API request require authentication with your API key and password. To request an API key, please contact us at info@farmaframe.be.

To authenticate yourself you have two options:

Alernatively you can use the client side javascript library to access a subset of the API features.

Rate limiting

All API endpoints are subject to rate limiting tied to your account. Public endpoints will be rate limited by IP address.

Our rate limiting implementation is based on a leaky bucket algorithm. This means you aren't alloted a fixed number of requests you can perform in a time periode (eg: 50000 requests per month). Instead we provide you with a flexible avarage consumption rate that can scale up to peak time demand (approximately 3% of your monthly allowance in 1 minute). This consumption rate is not expressed in requests but in request tokens. Most requests will consume one token. Some requests may consume more tokens.

All responses from the API will contain an X-RateLimit-Remaining header, informing you of the number of tokens available for immediate use. Should you run out of tokens you will receive an HTTP 429 response. The Retry-After header will specify when new tokens are available.

Rate limiting is tied to your api key. If you wish to use the same api key for multiple use cases some extra caution may be required on your part to assure that one use case cannot use up all available api calls.

Language negotation

All API endpoints require an Accept-Language header. Valid values for this header are nl and fr. Not specifying an Accept-Language header, or specifying an invalid value will result in a HTTP 406 response.

Caching

Some API calls can be cached by the client. Other API calls should never be cached by the client. Nearly all API endpoints will provide cache headers to inform you of this. Clients should follow these directives.

JSONP

The API supports JSONP. Simply provide a jsonp parameter to receive a jsonp response.