3. Introduction

3.1. SmartBL infrastructure

CargoX has created a platform, which enables you to transfer the Document of title between the parties. The platform itself is called Blockchain Document Transaction System and its first implementation is the SmartBL application, available at the domain https://app.smartbl.io/.

The platform itself is composed of three distinct parts:

  • The blockchain part, which includes the tokens, token dynamic and the smart contracts – all of these are based on the Ethereum platform;
  • The web application, which wraps around the blockchain code, adds some additional functionality, and allows users to interact with the application through well-known REST interfaces;
  • The front-end application developed using the services provided by the web application and presenting everything a nice graphical user interface.

This document describes the interaction with the BTDS platform on the level of web calls – REST API services.

3.2. Working environments

CargoX provides two environments:

Sandbox is meant for testing integrations and preparing your application for the go-live. Both environments provide the same functionality and run the same version of the application. The main differences are the following:

  1. The LIVE and SANDBOX environments do not share the database. Therefore, any accounts created on the SANDBOX environment need to be recreated on the live system once you are ready to go-live.
  2. The SANDBOX environment is connected to the test Ethereum network (Rinkeby at the time of writing). Consequently, the transactions will not show on the mainnet blockchain. As test networks can have issues and delays, CargoX reserves the right to change to another network or use a private network in the future.
  3. As things change and progress, SANDBOX may be flushed, and data deleted. You should rely on data on the sandbox network being persistent.

Note

Everything available through the web interface is also available via an API. Furthermore, the API introduces some special calls, which are not available in the application itself – the 3rd-party API.

3.3. API Availability and versioning

The API is available on the /api/ endpoint, for example:

Attention

As things progress, requirements and API may change. To make sure that the API is stable, it is usually versioned. At CargoX we have decided that our API will use URL versioning.

This means that each API endpoint includes a version of the interface in the URL. Changes between versions are always breaking changes and upgrading to a new version of the API requires changes in the code.

CargoX guarantees that the APIs under the same version are constant. No breaking changes to the available APIs will happen. However, the following are still permitted and your code must be able to handle the transitions gracefully:

  • Input object (e.g. JSON) that you POST or PUT onto the platform might get new (non-mandatory fields);
  • Output objects (e.g. JSON) that you GET or receive as a result of an action might get new fields;
  • New methods may appear in the API.
  • Error messages might get more defined - e.g. instead of returning a generic 400 or 500 error, the system might decide to return 403, or a custom code (e.g. 515).

3.4. API documentation

The API uses a self-documenting format. All documentation is available at the URLs, as explained below.

Note

This documentation references two versions of the API. Either v1 or v2. The API is available at specific endpoint. E.g.:

As both environments run the same version of the platform, the documentation is identical. The documentation explains in detail each specific API call and the parameters. API explorer is available directly on the API endpoint:

Both v1 and v2 APIs use the same authentication mechanisms, so you may mix and match the usage of both APIs independently. If a v2 API exist for you call, you will be notified by a header inside the v1 response.

v1 is currently active and there are no immediate plans to depricate it in the future. All new implementations should rely on the v2 API as much as possible as it's simpler to understand and use.

3.4.1. Version 1 (legacy)

The version 1 of the API is described in a separate section. v1 API is stable, complete and will not change other than through bugfixes. No new features will be added to this API.

Environment Redoc explorer Swagger client
Sandbox https://sandbox.smartbl.io/redoc/v1/ https://sandbox.smartbl.io/swagger/v1/
Live https://app.smartbl.io/redoc/v1/ https://app.smartbl.io/swagger/v1/

3.4.2. Version 2 (future)

This is the new in-the-making API and has its own segment in the documentation. It has been created from the ground up to be more clear and easy to use and understand. The API is stable but is not yet complete. The end goal is to replicate the functionality of the v1 API in this new interface. All new development and new features will be availble in the in this API only.

Environment Redoc explorer Swagger client
Sandbox https://sandbox.smartbl.io/redoc/v2/ https://sandbox.smartbl.io/swagger/v2/
Live https://app.smartbl.io/redoc/v2/ https://app.smartbl.io/swagger/v2/