API

Page last updated on April 20, 2018

Most of the Qobrix functionality is available both via the web interface and via the API.  This section describes some of the API concepts, approaches, techniques, and resources for more information.

Overview

There are many different options when it comes to the implementation of the API and web services.  For Qobrix, we are using REST/JSON.  REST provides a simple, yet reliable communication layer on top of the HTTP protocol, while JSON standardizes the format of the requests and responses.

Location and Versioning

Every Qobrix application has its API end-points located at /api/ URL path. The Qobrix API uses versioning for improved backward compatibility and easier transition from one implementation to the next.  API versions are represented but two numbers, separated with the dot.  For example: 1.0.  The first number indicates the major version of the API.  Different major versions of the API are most likely not fully compatible between each other (for example, 1.0 and 2.0).  In fact, future versions of the API might switch from REST/JSON implementation to something completely different, like, for example, GraphQL.  The second number indicates the minor version.  These are usually reserved for customer-specific changes and other per-project and per-application changes necessary.  Different minor versions are backward compatible between each other, as long as the major version is the same.  For example, 1.5 and 1.7 are compatible, because they are both based on the major version 1 of the API, and 1.5 and 2.5 are not compatible as they rely on different major versions (1 and 2 respectively).

API version can be specified as part of the URL path to the API end-point.  For example: /api/v1.0/ forces version 1.0 implementation.

API versioning hasn’t been introduced from the first day of Qobrix and only came into play much later.  For this reason, Qobrix supports API requests without any version number.  In such cases, Qobrix will always fallback on the version 1.0.

Documentation

Qobrix applications vary a great deal from one to another.  Different Qobrix features might enabled or disabled.  Qobrix module used for the application vary a lot (for example, Trading Accounts make a lot of sense in Qobrix Forex CRM, but are useless in Qobrix Real Esate CRM).  Module fields vary a lot even between very similar projects.   In order to provide a reliable and up-to-date documentation of the API functionality, we have integrated Qobrix with Swagger API documentation tool.

Qobrix - API - Swagger - v2.9.0

The API documentation for your Qobrix application is available at /swagger/ URL.  As with many other things in Qobrix, we realize that API documentation might be quite sensitive and it is not always desirable to have it publicly available.  By default, we do enable the documentation, but the administrators, developers, and system integrators can disable Swagger documentation via the .env file, using SWAGGER_CRAWL=0 variable.

Authentication and Authorization

Qobrix API uses JSON Web Tokens (JWT) for authentication and authorization (read RFC 7519 for more information).  This means each API request must include the valid API token so that the Qobrix system in question knows which user is trying to perform a given action, and thus can check and make sure that the user has all the appropriate access.

In order to get an API token, the API user first needs to send a request like this:

$ curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}' http://YOUR_URL/api/users/token.json

The above request, in more detail, has the following meaning:

  1. Set “Content-Type” request header to application/json.
  2. Set “Accept” request header to application/json.
  3. Set request data to JSON, which includes the valid username and password.
  4. Send a POST request to the /users/token.json API end-point.

The response to such request will be in JSON format.  In case of the error, the response would include the reason for the error, such as “Invalid username or password”.  In case of success, the response will include the JSON web token.  Here is an example of the successful response:

{
    "success": true,
    "data": {
        "token": "xyz123"
    }
}

Strictly speaking, it is not necessary to generate a new token for each and every API request.  Tokens are valid for the same period of time as application sessions.  These can be configured via the .env environment file, and are set to be 12 hours by default (overnight expiry).

Once the JSON web token has been successfully acquired, it should be included in all the API requests, using Authorization header, with “Bearer ” prefix.  For example:

$ curl -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer xyz123" -X GET http://YOUR_URL/api/leads.json