Introduction
How you can integrate software with Tachyon using public facing Application Programming Interfaces (API).
This guide is not aimed at the general reader, it's intended primarily for use by developers who want to create their own consumers, for example using PowerShell or C#.
To get the most from this guide you should have a solid understanding of Tachyon, APIs, HTTP Communication and web API terminology.
The Tachyon API will change as new functionality is introduced and other functionality is either deprecated or removed. For this reason you should integrate with a specific version of the Tachyon Consumer API, preferably the most recent one.
The Consumer API reference shows the minimum version of the API for a given endpoint and any differences between each version.
What is the Consumer API?
Tachyon exposes an API called Consumer API and 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 endpoints for the Tachyon Explorer or any other built-in Consumer. If the built-in Consumer can do something, your Consumer will be able to do it. You'll have to create a Consumer that you'll use and make sure that it's present in your license.
Please contact support@1e.com to set up a feature in your license that will contain your Consumer.
Accessing the Consumer 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 tool of choice.
To help you use the Consumer API we have designed:
Tachyon .NET Consumer SDK - written in .NET and providing an abstraction layer to make working with Tachyon easier
Consumer API reference - describing available API endpoints, expected received and returned payloads, permissions
How to guides - to perform common operations in Tachyon using the Consumer API, c overing basic use-cases with examples in raw JSON payload and Tachyon .NET Consumer SDK.
Tachyon Server versions from 3.3 have documentation you can access with a web browser. Go to https://<MyTachyonServer>/Consumer/swagger/ui/index#/ (replace <MyTachyonServer> with the address of your Tachyon installation) to view the API documentation.
Use the the built-in swagger documentation as your primary guide regardless of your chosen tool or language and consider Consumer API Reference as back-up source.
How do Consumers work?
Consumers do not have to be purpose-built programs. 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.
A Consumer is identified by its name and this name has to match between the license, its registration in Tachyon and each API call made. Consumer names are not case sensitive, so "MyConsumer" is considered the same as "MyCoNsUmEr". You can think of a Consumer name as an identifier, a passport if you will, that gains a piece of software access to Tachyon Consumer API. As an example, let's assume that you wish to have your own consumer and you want to call it "ScriptRunner". This means that your license file has to have a Consumer entry with the name="ScriptRunner", you have to register "ScriptRunner" as a Consumer in Tachyon and enable it, and you will have to add X-Tachyon-Consumer header field with the value of "ScriptRunner" to every API call you make using your chosen tool. Don't worry if this sounds complex, we will go through each of these elements on this page.
Many pieces of software can introduce themselves as the same consumer, for instance you can have a set of scripts using the same Consumer. Be aware that all software using the same Consumer shares that Consumer's limits and settings that are 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, that are already licensed. Any software wishing to access Tachyon must also be present in the license. The Consumer name used in the license must match the name you register with Tachyon using either Settings application or Consumer API directly.
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 using an API call. The name of the Consumer you use here must match the name you have in your license. Note that if a piece of software wishes to register a Consumer, it doesn't have to be a Consumer itself. Permissions, will be checked as usual, read Registering a new Consumer for details.
Enabled - a setting present in the license entry for the consumer and on a Consumer registered with Tachyon.
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 and licensing
Consumers must be present in the license file and be enabled.
Look in your license file for an entry like the one below (where [your consumer name here] is the name of your consumer):
Sample Consumer entry in the license file
<Consumer name="[your consumer name here]" enable="on"> </Consumer>
If you cannot find this entry, please contact 1E Support and ask for an updated license file.
The feature containing your Consumer might look something like this:
Consumer feature in a license file
<Feature name="Customer A Consumer">
<Consumer name="MyConsumer" enable="on"> </Consumer>
</Feature>Note
The consumer must have enable set to equal "on".
Using Consumers
Each time an API call is made, Tachyon checks if the:
Principal making the call has sufficient permissions to do that call
Consumer they're using fulfills the three prerequisites - licensed, registered with Tachyon and enabled.
The Consumer is checked first, the 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, 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) directly using the API. All the endpoints responsible for Consumer management are located in the Consumer's controller of the API. This is available under https://<MyTachyonServer>/Consumer/Consumers URI. Read the Consumer API reference documentation for details.
A Consumer can also be registered through the Tachyon 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. Set this by assigning the Principal to the Consumer Administrator role.
Consumers vs Principals
In addition to the concept of a Consumer, Tachyon has a concept of a Principals. A Principal can be a user or a group taken from Active Directory. While Tachyon does come with at least one Principal that represents a machine account (therefore a local account, not an Active Directory one), this Principal is created during installation for the purpose of internal communication between various Tachyon components and you cannot add non Active Directory Principals yourself.
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.
How do Consumers, Principals and Permissions interact
It is important to understand how Permissions interact with Consumers and Principals.
Consumers cannot be assigned Permissions. They cannot be limited to only certain Principals either. In short, Consumers have no link or interaction whatsoever with Permissions or Principals.
Principals have Permissions through Roles they are assigned to, as per standard RBAC model.
This means that a Principal will have the same set of Permissions regardless of what Consumer they use.
If you were to launch a web browser and open Tachyon Explorer, you would have exactly the same set of Permissions as if you had opened Guaranteed State application, made an API call through Postman or run a Powershell script that contacts Consumer API.
When Princiapls and Permissions are concerned, the Consumer is irrelevant. Any Consumer can be used, as long as it is licensed and registered in Tachyon. It is only a tool that is used to perform an action. For RBAC what matter is who performs the action.
What happens when I make a call to Consumer API?
Tachyon performs two independent checks when it receives an API call:
A Consumer API check for X-Tachyon-Consumer header is performed for the vast majority of API endpoints, Consumer management and Information endpoints being notable exceptions.
If given endpoint is excluded from Consumer name check, this first check concludes and the second check in performed.
Consumer API will check the header of the incoming request and retrieve the value of X-Tachyon-Consumer.
If this header is missing the call is rejected and an error is returned stating that X-Tachyon-Consumer field was missing in the header.
Consumer API verifies that the Consumer name obtained from X-Tachyon-Consumer represents a Consumer that is known to Tachyon, that said Consumer is licensed and enabled.
If any of these checks fail, the call is rejected and an error is returned that will describe the issue that caused the Consumer to be rejected, be that it not being registered, unlicensed etc.
Consumer API checks Permissions on the Principal making the call
If the calling Principal doesn't possess the necessary Permissions to perform the operation requested, the call is rejected and an error is returned.
Excercise in accessing Consumer API
Hello world example
First we'll try to determine if you can access the API by browsing to https://<MyTachyonServer>/Consumer/Information.
This endpoint doesn't require the X-Tachyon-Consumer field to be present in the request's header so can be made from a web browser.
If everything works you should see a piece of XML that will state the version of the product.
Performing this step will help you establish that everything it up and running and can be accessed via given URL.
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 in the picture) remember that not all versions handle Windows Authentication correctly. Please have a look at API testing tools page which discusses several tools and their configuration.
In the examples below we'll use Postman.
First, issue a GET request to https://<MyTachyonServer>/Consumer/SystemInformation
You should see something like the screenshot on the right.
This is because you didn't include X-Tachyon-Consumer in the request header.
 |
Now let us add this field to the header. The example on the right is using "Explorer" as the Consumer name, but you should use the name of you Consumer.
Now when you make the request you should see something like this:
You might see something like this:
Or like this:
In the case of the first error above, you've reached Tachyon and it's telling you the Principal you're using is not authorized. This can mean that it has not been added to Tachyon or does not have permissions to use the endpoint being called. The error you see follows the Tachyon standard error reporting mechanism described in Handling errors returned by Tachyon.
If you get a web page back, like in the second error, it means your request has been rejected by IIS, not Tachyon. This can mean there's a problem with the credentials supplied in the request (incorrect username or password), your IIS settings or the tool you're using. It can also be because your tool does not support Windows Authentication, or because Windows Authentication is disabled. Tachyon uses Windows Authentication for API calls so your chosen tool must support it.
Payload format
Most API endpoints use application JSON data formatting for expected and returned data.
Note
Be aware that some endpoints take multi-part form-data or in a few cases return an octet stream.
Read the Swagger documentation included in the product or Consumer API reference for the details of all endpoints provided by the Consumer API.
Downloading the Tachyon SDK
The Tachyon .NET Consumer SDK is available from the 1E Support Portal.
Download the version of TachyonSDK zip that you require for your version of Tachyon from the https://support.1e.com/.
Extract the files from the download zip to your choice of location.
Use your choice of tool or programming language, for example PowerShell or C# to create your Consumer.
For details of file versions, please refer Tachyon SDK release information.
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 to 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 to use in an ASP.NET application to help create a target for Tachyon offloading. It does not access Tachyon directly, it enables the creation of software Tachyon can access during the offloading process.
Read Tachyon Offloading SDK library for more information.