Version: 3



The purpose of this page is to explain how an application can integrate with Tachyon using public facing APIs exposed by Tachyon.

This guide assumes you are technically capable and, at least to a certain point, technically minded and posses at least basic knowledge about application programming interfaces and http communication.

The basics

Tachyon exposes an application programming interface (API) called Consumer API.

Any piece of software accessing this API is considered a Consumer, and Tachyon comes with several Consumers, like for instance Explorer, installed along with the server components.

If you are accessing Consumer API via an API testing tool, like Fiddler or Postman, that tool is considered a Consumer. Why this is important is described below.

All the Tachyon UIs you have seen use Consumer API. There is no separate, "special" API for Explorer or any other built-in Consumer. If the built-in Consumer can do something, your Consumer will also be able to do it.

Accessing the API

What am I going to need?

Any tool or programming language capable of issuing HTTP requests should be able to use Tachyon's Consumer API, so you can use the tool that fits your requirements the best.

We have a few things designed to help you on your journey.

  • Tachyon Consumer API reference documentation - this documentation described in detail the various API endpoints available, payloads they expect to receive and which they will return, permissions they require etc. This should be your primary reference guide when looking through the functionality exposed by the API. No matter what tool or language you will be using to access the API, this is the documentation you should get familiar with.
  • A "How do I" series of articles - this series of documents aims to provide a guide on how to perform some basic and frequently used operations in Tachyon using the Consumer API. These articles go through some basic use-cases and have two kinds of examples - one with raw JSON payload and one using Tachyon .NET Consumer SDK.
  • Software development kits written in .NET that make working with Tachyon easier by providing an abstraction layer.

How do Consumers work?

Consumers don't have to be purpose-built programs. As mentioned above, API testing tools are also considered Consumers.

Tachyon uses the concept of a Consumer to differentiate pieces of software accessing it. It also allows 3rd party software to be limited in its use of Tachyon (for instance, by defining how many simultaneous instructions given Consumer can issue), define where responses to instructions should be offloaded to etc.

A Consumer must fulfil a number of prerequisites in order to be allowed to access Tachyon:

  1. Consumer must be licensed. Tachyon comes with a number of Consumers, like Explorer and Settings, already licensed and any pieces of software that wish to access Tachyon must also be present in the license.
  2. Consumer must be registered with Tachyon. A number of system Consumers are registered when Tachyon is installed and all other Consumers can be registered after Tachyon has been installed. This can be done via Settings web application of via an API call. It is important to note that if a piece of software wishes to register a Consumer, it doesn't have to be a consumer. Permissions, however, will still be checked as per usual. Please see here for more details.
  3. Consumer must be Enabled. This is a setting on an already registered Consumer.

When all three prerequisites are fulfilled, the Consumer will be allowed to access Tachyon, subject to permissions assigned via Tachyon's Role Based Access Control (RBAC).

Consumers vs Principals

Aside from recognising the concept of a Consumer, Tachyon also has Principals. Principal can be a user or a group, taken from Active Directory.

So how do those to interact?

It's simple: Consumer is a piece of software. Principal is a user of that software.

Consumers are subject to Consumer check as described above.

Principals are subject to RBAC check.

As a rule of thumb, each time an API call is made by whomever, Tachyon will check if the Principal making the call has sufficient permissions to do that call and that the Consumer they're using is fulfils the three prerequisites mentioned above.

From a technical standpoint, Consumer is checked first, and Principal's permissions are checked second, only if the Consumer is successfully verified.

How does my software notify Tachyon what Consumer it is?

To define what Consumer is issuing the call, a "X-Tachyon-Consumer" field should be added to the header of the HTTP call. Because each HTTP call is independent, each call must incorporate this field in its header. Some API endpoints do not require or check this header, but vast majority do therefore it should be included in each call to the Consumer API.

Registering a new Consumer

To avoid chicken-and-egg situation, API endpoints pertaining to Consumers are not checking if the software calling them is a Consumer fulfilling the three requirements listed above. This allows Consumers to be added or removed by, for instance, their installation or uninstallation processes.

It is also worth remembering that although these API endpoint do not check for the X-Tachyon-Consumer HTTP header, the will still check the credentials of the calling user.

A Consumer can be registered (added) via the API directly. All the endpoints responsible for Consumer management are located in the Consumers controller of the API. This is available under https://my.Tachyon.server/Consumer/Consumers URI. Please have a look in the API reference documentation for details.

A Consumer can also be registered through the Settings web application. Browse to Configuration and select the "Consumers" menu item.

In order to manage consumers, Principal making the call must have Write permission on Consumers securable type. This can be achieved by assging the Principal to "Consumer Administrators" role.

Payload format

Vast majority of API endpoints use application/json data formatting for data they expect and data they return.

Some endpoints take multipart form-data, while others will return an octet stream, but those are few and far between.

Please refer to documentation of a specific endpoint to find out the details.

Available tools

SDK tools are available as a .NET nuget package from 1E nuget server.

Tachyon .NET Consumer SDK

Consumer SDK is a software development kit that contains an abstraction layer for the Consumer API.

In short, it has been designed to help build Consumers by abstracting the HTTP communication behind C# classes.

An introduction to the library can be found here, and if you're developing a .NET based application that will interface with Tachyon, you can use it along the the API reference and "How do I" guides.

Tachyon Offloading SDK

The Offloading SDK provides a managed DLL that can be used in an ASP.NET application to facilitate the creation of a target for Tachyon offloading.

It does not access Tachyon directly, but rather facilitates creation of software that will be accessed by Tachyon during offloading process.

Further information can be found here.