Exploring the APIs

We use Swagger to power charge your journey on the blockchain. Swagger is the standard way to expose RESTful APIs.

Where is it

You can access the Swagger explorer of the API. To find the API address go to Services in Forma, select the Instance you'd like to access and click Root Address. In the url add an extra "/docs".

Make sure you create and add the API Key in every request.

Basic structure

The Tellus API makes it easy for a developer to create a web, mobile, or IoT application from the API.

Endpoints are tagged for easier identification. templates are all the designs you created at the Admin Console.  execution-assets are the way you interact with assets from the blockchain. execution-transactions are the way you interact with transactions from the blockchain. default are general endpoints, for example the /server endpoint allows you to retrieve the basic data from the server about the identity running the Tellus Instance.

The logic

You usually retrieve Asset Templates and Transaction Templates created through the Admin Console with the  API,  and then based on the template you selected you can create and manage Assets and Transactions directly in your blockchain through the API as well.

You need to know the structure of the asset or transaction you will create or manage before you interact with them.

You can do that either dynamically or you can assume that your asset and transaction templates format won't change.

The best way for you to grasp the way to interact is by doing. So go to your Admin Console and play around a little bit creating Assets and Transactions.

You can use your Swagger UI to test APIs. Just select which one you want to test, and click the Try it out button. In the bottom, you will see the response.

You can also do it through an API tester like Postman.

In here you can see the structure of an Asset. As said before, you could manage those templates dynamically, or you can make fixed structures on your code to handle them. For example, let's explore how to create an asset.

{
	"identifier": "1233823",
	"name": "Bill Gates",
	"content": [{
		"name": "Age",
		"value": "60"	
	} ]
}
		

The properties from the Asset Template warn you about business rules, i.e.: if a field is required the property "nullable" will be false.

The same logic applies to transaction templates. Objects can be as simple or as complex as you need them.

For inserting and managing assets, you can see the rest of the API specification in the Swagger.

Next

Integration Flows

Architecture