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.
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, like for instance Explorer, preinstalled.
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:
- 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.
- 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.
- 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 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.
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.
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.
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.
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.