Torizon Cloud API (Beta)
Introductionβ
This article guides you on automating, extending and integrating the Torizon Cloud features through its REST API. It also brings information about enabling, testing and using the API in our solution.
If you are looking for reference documentation, check our OpenAPI Specification.
Why Use the Torizon Cloud APIβ
A REST API (Application Programming Interface) is a set of rules and protocols that allows different software applications to exchange resources with each other over the internet. The Torizon Cloud API defines the methods, data formats, and authentication mechanisms that enable your application to request and receive data or perform actions from Torizon Cloud using HTTP requests.
While we provide a comprehensive feature set in our Torizon Cloud Web UI, you can automate, extend and integrate its features in your solution using Torizon Cloud API.
- Automate: most of the tasks executed on the Torizon Cloud Web UI can be automated and incorporated into any workflow of your product development/maintenance environment, eliminating the need for manual intervention on the web platform.
- Extend: if you need features not provided in the Web UI platform, you can try implementing them by leveraging the API: filtering information for exhibition according to your product particularities or even conditional updates.
- Integrate: you can use the API to bring features such as updates, package management and device monitoring to your application or Web UI, giving your own users access to the powerful capabilities of the Torizon Cloud.
Common use cases:
- Fleet Management: integrate the Torizon Cloud features into your existing fleet management platform to have rich insights on the devices, such as installed software packages and device metrics.
- Domain translation: you can use the expertise of your support team to manage your devices without having to learn Torizon Cloud namings and UI, incorporating its features in your support platform.
- CI/CD Workflows: automate the deployment process and integrate it with the build of your application and OS images. While Torizon provides resources for easy automation of OS and application builds with TorizonCore Builder and Docker Containers, these artifacts can be easily deployed across multiple fleets using Torizon Cloud API.
Torizon Cloud API Featuresβ
Product Featuresβ
Most of the features available in the Web UI are accessible using the API:
- Devices and Fleet Management
- Software Packages Management
- Device Monitoring
- Secure OTA and Offline Updates
The Torizon Cloud Web UI is the standard platform to manage your account, repositories and connected applications.
Accounts & Sandboxβ
Due to security reasons, it is recommended that you set up a sandbox environment for evaluation and development. You can do this by creating different accounts for sandbox and production. Check our commercial plans to understand services and trial period.
Documentationβ
You can learn the API specifications on our Reference Documentation .
To download the OpenAPI specification file, click ./torizon-openapi.yaml:
Endpointsβ
For precise and complete information, check the Reference Documentation.
Check below a summary of useful functionalities available through the endpoints:
- Retrieve a list of devices in your repository
- Get detailed information on a single device
- Delete a single device
- Manually create a new device
- Retrieve device provisioning token to create a new device
- Additional Endpoints to get and set the information of the devices and fleets, such as display name, installed packages, assigned updates, network information and device notes
- Get information about all fleets in your repository
- Create a new fleet
- Get information on all devices in a fleet
- Add devices to a fleet
- Remove devices from a fleet
- Delete a fleet
- List packages from external sources - such as Toradex images
- List packages you uploaded
- Upload a new package
- Edit metadata about a package
- Delete a package
- Deploy an update across multiple devices or a fleet
- Cancel a Pending Update
- List all lockboxes from a repository
- List all lockboxes from a repository including their details
- Get Raw Uptane metadata for a lockbox
- Define a new lockbox or update an existing one
- Get a list of Metrics available in your account
- Get time-bucketed data from a specific device
- Get time-bucketed data from a specific fleet
How to Use Torizon Cloud APIβ
Preparationβ
Get an account on https://app.torizon.io with access to the feature. Check the commercial plans for more information.
1. Create an API Clientβ
1.1. Enter your Torizon Cloud account. On the API Client Manager section, click Create API Client
:
1.2. Give the API Client a name and a description. Select the API V2 (beta) Client Type:
1.3. Click or select the Client Secret field to copy and use it during your testing and integration procedures. Note that you won't be able to see the secret after closing the form:
2. Check the API Endpointsβ
There are several ways for you to evaluate Torizon Cloud API:
- Curl calls: Command-line tool to transfer data between machines using one of many supported protocols (in this case HTTP is relevant). You can easily test the API with curl commands in a Linux terminal.
- Restish: CLI for interacting with REST-ish HTTP APIs given an OpenAPI Spec. You can use it to automatically generate commands inside Linux Terminal for direct calls to the API endpoints.
- Postman: Tool to help design, build, test and iterate REST APIs. It allows importing OpenAPI documentation to easily test endpoints.
- From the application: Using HTTP utilities from your programming language libraries.
- OpenAPI Generator: Tool that allows the generation of API client libraries (SDK generation), server stubs, documentation, and configuration automatically given an OpenAPI Spec.
The simplest way to check the API endpoint is using our Online Documentation
2.1. Access the authorization form:
2.2. Enter a valid token to get authorization for the API requests. Refer to the Authentication section to learn how to obtain the token:
2.3. Execute calls to the API to get examples of the requests.
3. Integrate Into Your Solutionβ
Having understood and designed your integration workflow, you can proceed to add calls to Torizon Cloud API in your solution. Remember, you can use the libraries available from the programming language your project uses and even leverage the SDK generated by tools such as OpenAPI Generator, as mentioned above.
There are important aspects you should evaluate when integrating Torizon Cloud API into your solution:
- API Documentation: Understand and comply with request and response formats, authentication requirements, and any other relevant details of the available endpoints.
- Rate Limits and Throttling: proper handling of your end users will prevent excessive requests to Torizon Cloud API and potential service disruptions.
- Versioning and Upgrades: Understand that this API is versioned and consider the impact of future upgrades on your integration.
- Scalability and Performance: Consider factors such as response times, concurrency, and data volume to ensure Torizon Cloud fulfill your requirements under different usage scenarios.
- Data Validation and Formatting: Pay attention to data formats, units of measurement, and any specific constraints specified in the API documentation.
- Error Handling: properly handling error codes, error messages, and fallback options will help provide a robust end-user experience.
Authentication and Securityβ
Torizon Cloud API uses OAuth2 - Client Credential flow. This means you need a token to successfully execute requests to the API.
Get a Tokenβ
Using your Client ID and Secret you can obtain a valid token to execute requests for the API.
Token URL: https://kc.torizon.io/auth/realms/ota-users/protocol/openid-connect/token
This is a request example using curl
to get the token:
$ curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=<yourClientId>&client_secret=<yourClientSecret>" \
https://kc.torizon.io/auth/realms/ota-users/protocol/openid-connect/token
Make sure you follow best practices for securely storing credentials. Anyone with access to these credentials can send malicious software to all devices in the repository.
Manage Tokensβ
Define the token lifetime during the creation of the API Client, according to your use case requirements. For instance, in CI/CD environments you should generate the token just before the API calls, using the securely stored keys. After the pipeline is completed, you don't need the token, so it can have a short lifetime.
If needed, delete a Client on the Torizon Cloud Web UI, under the section My Account > API Client Manager. This will immediately invalidate all the tokens generated with this Client:
CI/CDβ
Torizon IDE Extension brings built-in actions that use the Torizon Cloud API to deploy your OS and application packages to devices or fleets. The provided templates already come with a JSON schema for speeding up the configuration of your GitLab and GitHub CI environment. You can use this as an example to implement automation on other CI/CD environments.
When you create a project using one of the Templates, the Torizon IDE extension creates the configuration files for GitHub and GitLab. If you want to learn how to implement a CI/CD workflow, see CI/CD - Configure Projects to Run CI Pipelines.
Standards & Architectureβ
RESTβ
While REST is not a standard or protocol, it is an important set of architectural constraints that are followed by modern APIs. Being a widely adopted architecture, it allows for easy understanding and fast integration. Torizon Cloud API is implemented as a REST-like API, which means that the main constraints from REST architecture are followed.
OpenAPIβ
As defined on OpenAPI Website:
The OpenAPI Specification is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs.
Torizon Cloud API complies with OpenAPI specifications, also contributing to its easy and fast integration capabilities.