Version: 13
restore

Contents

Introduction

This page explains how software 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. It also assumes basic knowledge of web API terminology.

The basics

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

Any software accessing this API is considered a Consumer, and Tachyon comes with several Consumers preinstalled, such as the Explorer interface.

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 describes in detail the various API endpoints available, payloads they expect to receive and payloads 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.
    Also, Tachyon Server versions from 3.3 onward ship with live documentation that can be accessed via a web browser. Simply browse to https://my.tachyon.server/Consumer/swagger/ui/index#/ (after replacing "my.tachyon.server" with the address of your Tachyon installation) and after a brief loading screen you'll see the entire API documentation.
  • 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. A Python or Powershell script can also be a Consumer.

Tachyon uses the concept of a Consumer to differentiate various 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.

Multiple pieces of software can introduce themselves as the same consumer. You can have, for instance, a set of scripts that all use the same Consumer. It is worth remembering though, that all the software that uses the same Consumer will share that Consumer's limits and settings set inside Tachyon.

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 wishes 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. The call will still be subject to permissions assigned via Tachyon's Role Based Access Control (RBAC) to the Principal making the call.

Consumers vs Principals

Aside from having 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 the user of that software. By "user" we mean something or someone who uses software. A machine account running a service is a user even though it is not a person.

Consumers are subject to Consumer check as described above.

Principals are subject to RBAC checks.


As a rule of thumb, each time an API call is made, Tachyon will check if the Principal making the call has sufficient permissions to do that call and that the Consumer they're using 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 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 permissions of the calling Principal.

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 assigning the Principal to "Consumer Administrators" role.

Hello world example

As the first step, you should determine if you can access the API at all. To do that, browse to https://my.tachyon.server/Consumer/Information in your chosen browser.

If everything is working you should see something like this:

Next step is accessing the API using an API testing tool, like Postman or Fiddler. With postman (which is what you can see on the screen shots) it is worth remembering that not all versions handle Windows Authentication correctly.

Use the tool to issue a GET request to https://my.tachyon.server/Consumer/SystemInformation

You should see something like this being returned:

If you see something like this coming back:

Don't worry. You've reached Tachyon and it's telling you that the Principal you're using is not authorized, which might mean that is hasn't been added to Tachyon or doesn't have permissions to use the endpoint being called.

The error you see follows Tachyon's standard error reporting mechanism as described on Handle errors returned by Tachyon page.

If, however, you're getting a web page back:

it means you've been rejected by IIS, not Tachyon. This might mean there's an issue with either IIS settings or with the tool you're using. It might be because it doesn't support Windows Auth, or because windows Auth is disabled.

Tachyon uses Windows Auth for API calls so your chosen tool must support it.

API versions

Tachyon API will change as the time goes on. As changes are made, new functionality is introduced and old might be deprecated or even removed altogether.

The important thing to remember is that you should always aim to integrate with specific version of Tachyon's Consumer API, preferably the latest one available.

Consumer API reference documentation will point out what is the minimum version of the API for given endpoint and differences between versions, should any exist.

Payload format

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

Some endpoints take multi-part 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.

It has been designed to help build Consumers by abstracting away the complexities of HTTP communication behind C# classes, providing models for data sent to Tachyon and received from it.

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.