nVIRO API Developer Guide
- Will Rensmith
- Ted Morris
API Services List
nVIRO publishes a web page where services can be viewed:
Core application API URL:
{Base nViro Service URL}/metadataUser-defined API URL:
{Base nViro Service URL}/metadata?type=api
User-Defined APIs (nVISAGE/Datahub)
nVIRO nVISAGE Data Viewer can be used to create and publish REST Web Services or APIs that can be used by third-party and custom applications to retrieve data from the nVIRO DataHub.
API services are created using the nVISAGE Data Viewer in the same way that a conventional report would be developed. To make a report available as an API service, the user simply saves the desired report to the API folder when complete. Reports saved to the API folder will be exposed as API services automatically/
Authentication
Authentication can be performed with nVIRO username/password or an assigned API Key.
Username/Password Authentication
Use your nVIRO user account to authenticate via the REST API.
See {Base nViro Service URL}/json/metadata?op=AuthRequest for description.
Route: {Base nViro Service URL}/auth (POST)
POST { "username": "[username]", "password": "[password]" }
API Key Authentication
Starting with nVIRO release 2024.2, user accounts can be assigned an API key.
Keys can be generated and revoked from the User Details screen. The option to create and manage API keys for user accounts must be configured at the system level. Contact Windsor if you want this feature enabled.
The API Key can be used in lieu of the user’s normal password in the authentication request. Using an API Key to authenticate will bypass two-factor authentication, if enabled.
Header Attributes
Accept
The Accept property can be used to specify the format in which data will be presented in a response (e.g., JSON or CSV). By default, all data is returned in JSON format, but data can be returned in a CSV format, when appropriate using this property.
CSV: text/csv
JSON: application/json
Example
For JSON: Accept: application/json For CSV: Accept: application/csv |
In the first example above, the response will be return as JSON. In the second example above, the response will be return as CSV.
Query Parameters
Each service can enable many service parameters. These query parameters can be defined within the “queryParameters” element. The following section describes the query parameters that are available for the service.
filter
The "filter" array query property allows an array of elements to be used to filter the results returned in the service response. Each element in the array is added to the filter as an OR logical operation. Each property for each element in the array is added to the filter as an AND logical operation. Any property that is associated with the element that is returned by the service can be used in the filter.
Example:
http.get('/service/', { params: {
queryParams: { filter: [ { name: 'S/%', type: 'Administrator' },
{ name: 'M/%', workgroup: 'Permits' },
{ isActive: false } ] }
}In the example above, notice the use of the wildcard query sequence '/%' which can appear multiple times anywhere in a query string value. This example will return all elements where:
name starts with 'S' AND type is 'Administrator'
OR
name starts with 'M' AND workgroup is 'Permits'
OR
isActive is false
orderBy Property
The "orderBy" string-array query property allows an array of string elements to be used to order the results returned in the service response in ascending or descending order. Each element in the array contains the name of the property to order by, followed by an optional "asc" or "desc" qualifier; "asc" is the default if not specified. The result elements are ordered sequentially according to the order of the properties in the "orderBy" array.
Example:
http.get('/service/', { params: {
queryParams: { orderBy: [ 'workgroupName', 'startDate desc' ] }
}});The example above will return the service results ordered first by workgroupName, then by descending startDate.
Top and Skip Properties
The "top" and "skip" query properties allow paging of the results returned in the service response. The "top" property indicates that, at most, "top" number of results will be returned, and the "skip" property indicates that "skip" number of results will be skipped over before "top" number of results are returned. For example, if we had a grid with a page size of 20 and we wanted to display results for the fifth page, we would use "top" = 20 and "skip" = 20 * 4 = 80 (skip over first four pages of results to display the fifth page). Note that the use of "top" and "skip" almost always requires the use of the "orderBy" property, as well, so that results are returned in a consistent (and not random) order.
Example
http.get('/service/', { params: {
queryParams: { orderBy: [ 'workgroup', 'startDate desc' ], top: 20, skip: 80 }
}});The example above will return up to 20 service results, skipping over the first 80 results, ordered first by workgroup, then by descending startDate.
Distinct Property
The "distinct" string-array query property specifies that only distinct property values should be returned in the service response.
Example
The example above will return only the distinct service results for the combination of 'workgroup' and 'programArea'.
Additional Service Attributes
The following are the additional service attributes that are available for use, when needed.
Query-By-Id Property
All services can be queried by id. In this case, the id of the element to be returned is appended to the end of the service URL, like so: /service/id.
Example
The example above will return a single element with the specified id in the queryResults array (if the element exists).
loadChildren Property (not currently available)
Loads any child arrays that are related to parent object. This attribute is only available for GET services and is dependent upon availability for the service based on the existence of a relational structure. As an example, you could load all documents associated to a given permit using this attribute.
Example
includeMetadataInResponse Property
Returns all metadata in the response, describing the properties of the response. This will include properties such as data types, read only, default value, labels, etc. See Service Metadata section below for additional details of metadata types.
Note: Metadata will be returned, by default.
Example
mergeMetadataInResponse Property
Restructures the response so that the metadata for each property is nested immediately under it as opposed to a big stand-alone metadata block beneath all the properties. This property is available to ease parsing of metadata, when needed. This will include properties such as data types, read only, default value, labels, etc. See Service Metadata section below for additional details of metadata types.
Note: this property is not available for dynamic services as metadata is merged with response for dynamic services.
Example