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 choice of tool.
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, 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://<MyTachyonServer>/Consumer/swagger/ui/index#/ (replace <MyTachyonServer> with the address of your Tachyon installation) to view the API documentation.
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.
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):
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:
The consumer must have enable set to equal "on".
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
- 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 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.
Hello world example
Determine if you can access the API by browsing to https://<MyTachyonServer>/Consumer/Information.
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 in the picture) remember that not all versions handle Windows Authentication correctly.
Use Postman to issue a GET request to https://<MyTachyonServer>/Consumer/SystemInformation
You should see something like this:
If something like this gets returned:
Or this view:
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 it means you have been rejected by IIS, not Tachyon. This can mean there's a problem with 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.
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 from the Release portal.
For internal 1E staff they're also available as a .NET NuGet package. Available 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 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
Page not found for multiexcerpt macro. The page: TCN41:Ex 3 - TCN Dev v4.1 - Offloading Responses was not found. Please check/update the page name used in the 'multiexcerpt-include macro.
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.