What REST APIs are Available in BarTender Cloud?
Question
What APIs are available? What does each one do?
Applicable to
- BarTender Cloud REST API
- Automation subscriptions
Security API
The Security API manages all things users, permissions, group management, and role management.
Security basics
Security works a little differently in Cloud than on-prem BarTender. The big key difference is that there is no concept of a deny permission.
On-prem BarTender has a concept of "deny", which overwrites any "allow" permission for a particular user as long as that deny is there (whether it is from a group or explicitly set on the user itself). This sets the user's effective permission as "always deny" no matter if something is allowed elsewhere.
Cloud does not have anything so explicit and instead operates on an "allowed" or "not allowed" permission system. It creates a union of all sources (roles, groups, individual settings) to determine if a user is allowed an action or not. If a user is allowed to do something in one group, it is allowed to do that thing even if another one of the user's groups does not have an "allow" permission set. For example, if User A belongs to the document management group (which can manage documents) but also belongs to the print operator group (which only has permissions to print), User A has permissions to manage documents because one of the groups says so.
User management
The API can do the following
- Create a user
- Delete a user
- Update user information
Role management
Roles are essentially containers for permissions. These permissions are assigned to all users contained within that specific role.
Roles are assigned to groups and users to set their permissions. These permissions can be used to set permissions on files in the web interface or via the API. They also can control if users or groups have access to specific APIs.
Printers API
The Printers API (sometimes called Print Management API) handles all things printers. This includes querying connected printers, obtaining printer information, and printing job statuses. At the moment, there are no API calls for querying Print History.
Many of the API calls are handled by the Print Controller Service, which communicates with the Print Gateway Service running locally on client computers.
Printer IDs
Printer IDs are a unique means to identify a printer within a tenant space. Each printer is identified by the client's name + the printer name
- printer:<clientname>/<printer_name>
For example, if a Zebra was a networked printer and connected to multiple clients, each client would have their own ID for this same printer. So the printer could appear as printer:mariopc/Zebra_105, printer:luigipc/Zebra_105, and printer:bowserpc/Zebra105 to uniquely identify which client is going to print to this printer. This does not affect licensing as licensing isn't determined by printer, so there is no duplication. Simply an identification to tell the Print Controller Service where to send the job.
Librarian API
The Librarian API is the REST API that works with files and folders stored within Librarian space. You can think of it as the file and folder manager via API calls. It has access to both Librarian spaces and can work with files and folders in both. The Librarian API does not print documents.
Librarian URIs
Librarian space has its own set of URIs that can identify a file or folder plus any additional information needed to retrieve the correct version item from within Librarian space and in which space the file or folder is located. The URIs are not only used in the Librarian API but also in the Action API to reference any file stored in Librarian space. File URIs are used by both APIs but folder URIs are generally used only by the Librarian API.
The general syntax for a URI is
- librarian://<space>/<path>[?parameter1=value1¶meter2=value2]
Values and parameters can be chained on the end using an &. The ? is only needed if parameters are present.
The two spaces are Main and $temp.
Examples URIs
Main space
- librarian://Main/Shipping/Label.btw
- librarian://Main/MyLabel.btw?version=3
$temp space
- librarian://$temp/Work/File.txt
- librarian://$temp/label.btw
Actions API
The Cloud Action API tells the Cloud to automate or update print jobs. While this resembles the BarTender REST API>and has similar actions, the Action API can only take calls in YAML and has actions limited by what is deemed safe to do in a Cloud environment. Database actions and actions such as Execute SQL will be missing from the API. For a full list, refer to the API documentation.
In addition to printing labels, the Action API can retrieve information about current actions running as well as perform some actions on folders and files. Most folder tasks will be handled by the Librarian API.
Reliance on other APIs
If you don't know the exact location of a resource or the proper address, you can use other APIs to find the information for you:
- Librarian API for the file location
- Print API for the printer name and information.
As these are separate APIs, you will need more than one call to retrieve the needed information. If you already know it, you can skip the extra calls and make the action call right away.