About Integrations
The barometerIT REST API provides bidirectional integration capabilities between barometerIT and other applications through the barometerIT API management layer, either through a Boomi iPaas connector or subscriber, or directly.
The basic REST documentation can be found at the bottom of this article.
barometerIT can be integrated with the systems from the business areas across the enterprise, for example:
- Configuration management databases (e.g. ServiceNow)
- Identification management (e.g. Microsoft Active Directory)
- IT financial management (e.g. IBM Tivoli Suite)
- Knowledge management (e.g. Microsoft SharePoint)
- Project portfolio management (e.g. Changepoint Daptiv)
Contents
REST API Introduction
In October 2013, we released a new version of the barometerIT application user interface. As part of this initiative, barometerIT was brought up to date with the latest "decoupled" patterns for user interface versus back-end architecture. At that time, barometerIT was outfitted with a full suite of REST APIs. To date, only the user-facing application was granted access to these APIs. We presently have an initiative underway to expose these directly to our customers.
REST APIs have a number of advantages over WSDL/SOAP services, including:
- Much easier for barometerIT to develop and maintain (which means more features for you).
- Much easier for your developers to use.
- A stateless, session-less authentication model (some simpler automation tools can't negotiate sessions).
The barometerIT REST API is in beta release. Please note, the REST API has been serving the front-end UI for some time and the services themselves are well-tested. The API is in beta release because we are still in the process of polishing and packaging them for public consumption. We are presently looking for early adopters, who are willing to work closely with us through this period.
This documentation is intended to provide a technical overview of bIT REST API principles and patterns. It is not intended to be an implementation guide. For detailed implementation assistance, please contact support@barometerit.com with an explanation of your use case and the data and operations in which you are interested. There is a Postman collection attached to this document that contain examples for the available REST requests. (Download Collection)
Tenant-End-Point
In the REST APIs examples you will see [tenant-end-point] in the URL, this is your tenant's URL. For example, https://example.barometerit.com.
Versions
barometerIT's REST API version follows the same iteration cycle as the application. Our release note will tell you which versions are available. We also allow the placeholder value for the current version. If you use "c" in version section of a request, you'll use the current version of the API to process that request. For example, https://example.barometerit.com/api/c/entities
Authentication
The REST APIs use Basic Auth, based on credentials you create as a Person record in barometerIT.
User
You must create a user. This represents a real person (like yourself), or it can be a "machine account" integration-only user. Please visit "Service Accounts" for information about creating an integration-only user.
Your user must be invited (to join barometerIT) by a User Administrator, and you must accept the invitation.
Roles (Permissions)
If you intend to use this user to make updates, you will also need to be granted the appropriate Editor roles.
Content Type
Your HTTP headers must negotiate certain content types as expected by the API.
Most barometerIT REST API POST requests expect:
Content-Type: application/json;charset=UTF-8
If your request does not specify that you will accept the content types returned by the server, you will received an HTTP 406 error. Most barometerIT REST API requests expect:
Accept: application/json;charset=UTF-8
Query Parameters
Simple parameters are usually passed according to "Query" convention, on the URL (HTTP GET -style).
JSON Parameters
More complex input (such as updates to field values) is usually passed as JSON content in the body of your request (HTTP POST -style).
Content Type (Response)
Most barometerIT REST API operations will respond with ...
Content-Type: application/json;charset=UTF-8
JSON Responses
Most responses return JSON as body content. The GET request reports/{bn} for example returns text/plain.
API Patterns
The barometerIT API follows a simple URL pattern for collections. /collection1/{collectionOneId}/collection2{collectionTwoId}. Some of the operations aren't collections, like "Search"; these are laid out by type. /search/{searchType}.
Operations
The following section highlights some of the more useful operations you may wish to use. For more information, contact support@barometerit.com with details regarding your use case and needs.
Notice that API operations are generic. There is no "read System" operation, only "read entity". Much of the API operates on Barometer Numbers (BNs) and the three-character codes that represents an entity (e.g. Organization always uses code "ORG"). You can find all the entity code in the Getting Started document.
Entity service
Execute basic Create, Read, Update, and Delete operations on an entity. This service also helps you assign field values on an entity.
Field Services
Execute Create, Read, Update, and Delete operations on fields.
Fieldset Services
Execute Create, Read, Update, and Delete operations on fieldsets.
Filter Services
Build filter strings that allow you to limit content of a collection request.
Reporting Service
Use the RESTful reporting service to request a snapshot of a report in CSV format.
NOTE
You can perform POSTs and GETs only. DELETEs and UPDATEs are not supported.
- Create the report in barometerIT.
- Using the API, do the following:
- Generate a new report asset, which is the BN of the report snapshot (Asset BN).
- (Optional) Use the Asset BN to read the size of the report asset.
- Download the report asset, which returns the report results in CSV format.
- Save the report asset as a CSV file.
- You can upload the CSV file as a document into barometerIT, from where users can access it.
Search Service
Use the Search Service to search for entities using a searchString, and specify the number of results to be returned. You can filter the request by entity type.