This page explains how to integrate software with Tachyon using public facing Application Programming Interfaces (API).
To get the most from this guide we recommend you have previous knowledge of APIs, HTTP Communication and web API terminology.
Tachyon exposes an API called Consumer API.
Any software accessing this API is a Consumer. Tachyon comes with several preinstalled Consumers, like the Tachyon Explorer interface. If you access the Consumer API using an API testing tool, like Fiddler or Postman, these tools are also considered Consumers. Every Tachyon UI uses the Consumer API.
There are no separate, "special" API for the Explorer or any other built-in Consumer. If the built-in Consumer can do something, your Consumer will 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 the Tachyon Consumer API. This means you can use your own choice of tool.
To help you use the Consumer API we have designed:
- Software development kits - written in .NET to make working with Tachyon easier by providing an abstraction layer
- Consumer API Reference - describing available API endpoints, expected received and returned payloads, permissions they need etc
- How to guides - to perform common operations in Tachyon using the Consumer API. Covering basic use-cases with examples in raw JSON payload and Tachyon .NET Consumer SDK.
Use the Consumer API Reference as your primary guide (regardless of your chosen tool or language). Tachyon Server versions from 3.3 have documentation you can access with a web browser. Go to https://my.tachyon.server/Consumer/swagger/ui/index#/ (replacing my.tachyon.server with the address of your Tachyon installation) to view the API documentation.
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 the various pieces of software accessing it. It also limits 3rd party software in its use of Tachyon (for example, by defining how many simultaneous instructions a given Consumer can issue) or define where responses to instructions should be offloaded to.
Many 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 fulfill a number of prerequisites to access Tachyon. Consumers 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.
- Registered with Tachyon - A number of system Consumers are registered when installing Tachyon. All other Consumers can be registered after installing Tachyon using Settings web application or 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, will be checked as usual, read Registering a new Consumer for details.
- Enabled - is a setting on an already registered Consumer.
When all three prerequisites are met, the Consumer is allowed to access Tachyon. The API call will be subject to permissions assigned using Tachyon Role Based Access Control (RBAC) to the Principal making the call.
Consumers vs Principals
In addition to the concept of a Consumer, Tachyon has Principals. A Principal can be a user or a group, taken from Active Directory.
A Consumer is a piece of software. A Principal is the user of that software. A "user" is something or someone using the software, for example a computer account running a service is a user even though it's not a person. Consumers are subject to Consumer check as described above. Principals are subject to RBAC checks.
Each time an API call is made, Tachyon checks if the Principal making the call has sufficient permissions to do that call and the Consumer they're using fulfills the three prerequisites mentioned above. The Consumer is checked first, and Principal's permissions are checked second only if the Consumer is verified successfully.
How does software notify Tachyon what Consumer it is?
To define what Consumer is issuing the call, add an X-Tachyon-Consumer field to the header of the HTTP call. Because each HTTP call is independent, each call must include this field in its header. Some API endpoints do not require or check this header, but most do, so it should be included in each Consumer API call
Registering a new Consumer
API endpoints relating to Consumers do not check if the software calling them is a Consumer that meets the three prerequisites listed above. This means Consumers can be added or removed by, for instance, their installation or uninstall processes. Although these API endpoints do not check for the X-Tachyon-Consumer HTTP header, they will always check the permissions of the calling Principal.
A Consumer can be registered (added) using the API directly. All the endpoints responsible for Consumer management are located in the Consumers controller of the API. This is available under URI. Read the Consumer 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.
To manage consumers, the Principal making the call must have Write permission on Consumers securable type. Do this by assigning the Principal to the Consumer Administrator role.
Hello world example
Determine if you can access the API by browsing to.
If everything works you should see something like:
Next, access the API using an API testing tool, like Postman www.getpostman.com or Telerik Fiddler https://www.telerik.com/fiddler. With Postman (shown below) it's worth remembering that not all versions handle Windows Authentication correctly.
Use Postman to issue a GET request to https://my.tachyon.server/Consumer/SystemInformation
You should see something like this:
If something like this is returned:
You've reached Tachyon and it's telling you the Principal you're using is not authorized. This can mean that it hasn't been added to Tachyon or doesn't have permissions to use the endpoint being called. The error you see follows the Tachyon standard error reporting mechanism described in Handle errors returned by Tachyon.
If you get a web page back it means you've been rejected by IIS, not Tachyon. This can mean there's an issue with your IIS settings or the tool you're using. It can also be because your tool doesn't support Windows Authentication, or because Windows Authentication is disabled. Tachyon uses Windows Authentication for API calls so your chosen tool must support it.
Tachyon API will change as new functionality is introduced and other functionality might be deprecated or removed.
For this reason you should integrate with specific version of the Tachyon Consumer API, preferably the most recent one.
The Consumer API reference documentation shows the minimum version of the API is for a given endpoint and any differences between each version.
Most API endpoints use application/JSON data formatting for expected and returned data.
Be aware that some endpoints take multi-part form-data or in a few cases return an octet stream.
Read the Consumer API Reference for the details of all endpoints provided by the Consumer API.
SDK tools are available as a .NET NuGet package from the 1E NuGet server http://nuget/api/v2/.
Tachyon .NET Consumer SDK
The Tachyon .NET Consumer SDK contains an abstraction layer for the Consumer API. The layer is designed to help build Consumers by abstracting away the complexities of HTTP communication behind C# classes and providing models for the data sent to and received from Tachyon. If you're developing a .NET based application that will interface with Tachyon, use the SDK library with the Consumer API Reference and How to guides.
Read Tachyon Consumer SDK library for more information.
Tachyon Offloading SDK
The Tachyon Offloading SDK provides a managed DLL that can be used in an ASP.NET application to help the creation of a target for Tachyon offloading. It does not access Tachyon directly, but rather enables the creation of software Tachyon can access during the offloading process.
Read Tachyon Offloading SDK library for more information.