API Types

There are several different types of APIs:

Web API

The Web Access API provides access is a static API segment that provides access to OmniFi Web. The main purpose is to read report definitions, execution logs and download report and endpoint output from previous executions, but you can also trigger execution of reports and tasks via API calls.

The Web Access REST API is available from <Service URL>/api/web. The endpoint https://host:port/api/web/reports will for example list all report workbooks in the system.

Autotest API

The Autotest Access API is a static API segment providing the ability to automate Autotest. You can create and manage workspaces, export/import collateral and trigger executions. This is useful for integrating automated testing into automated environment management and enterprise CI/CD pipelines.

The Autotest Access REST API is available from <Service URL>/api/autotest. The endpoint https://host:port/api/autotest/workspaces will for example list all workspaces in the system.

Custom API

The Custom Access API is available in two different formats:

1. <Service URL>/api/data
2. <Service URL>/api/odata.

Functionally the data and odata formats are equivalent, however the odata format provides metadata which allows client tools to auto-generate an appropriate UI to configure the request. Microsoft Power BI does this for example.

Three types of API endpoints can be published Function, Snapshot and Import.

Function

A function endpoint represents a data retrieval process that can be triggered by calling the API. A function can be parameterized, allowing the end user to define e.g. portfolio, period and other parameters to the underlying report. Because of this it is also slightly more complicated to use, as you must encode parameter values as a part of the request URL.

Function endpoints are very flexible, and well suited for publication to more advanced, trusted users and interface scripts, especially if they require very fresh data. You can schedule updates of a function endpoint at regular intervals to populate the cache, but end users still have the option to request execution and fresh data through use of the MaxAge argument.

Function data is personal per login. Data may be served from the cache, but end users can request immediate execution to get fresh data.

Snapshot

A snapshot endpoint is a table of cached report data populated by a schedule in Web. Snapshots are a simpler form of endpoint that doesn’t accept parameters when used, and the where the end user can only request cached data. Data for a snapshot is updated via scheduling, leaving the publisher in full control over what data is accessible and when it is updated from the source system.

Snapshots are less flexible but easier to use, and are suitable where you want to be in full control over the content and system load.

Snapshot data is shared between all users who have access to the endpoint.

Import

An import endpoint is a parameterized Data Processing operation that can be triggered using API calls. A report data set is used to provide the Data Processing input, while static endpoint configuration provides the service header. Parameter values are provided both to the report execution and the subsequent Data Processing execution allowing flexible parameterization.

Contrary to Function and Snapshot, Import endpoints are accessible though HTTP POST requests. Parameter values are supplied in the request body rather than as URI parameters.

Import endpoints support batch operations; The request body is made up of an array of parameter sets. Running batches is far more efficient than calling the endpoint repeatedly. To execute a single operation simply provide an array with a single set of parameters.

Import endpoints are accessible to users that have explicitly been granted access to it.

Accessing Metadata

API metadata is accessible from OData, by sending an HTTP GET request to <Service URL>/odata/$metadata, for example in a web browser. The response is an XML listing all endpoints and their respective arguments and return metadata that can be interpreted by OData enabled client tools.

If OData is not enabled, or your client tool cannot interpret the metadata, you need to visit the API Management page in OmniFi Web and drill into the details of each endpoint.