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:
- The LIVE environment, available at https://app.smartbl.io/
- The SANDBOX environment, available at https://demo.smartbl.io/
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:
- 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.
- 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.
- As things change and progress, SANDBOX may be flushed, and data deleted. You should rely on data on the sandbox network being persistent.
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:
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
PUTonto the platform might get new (non-mandatory fields);
- Output objects (e.g. JSON) that you
GETor 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
500error, the system might decide to return
403, or a custom code (e.g.
3.4. API documentation¶
The API uses a self-documenting format. All documentation is available at the URLs, as explained below.
This documentation references two versions of the API. Either
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:
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 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|
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
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|