Using REST API resources
Actuate provides REST API resources using the HTTP protocol. To make a request, use a REST‑enabled markup or platform to form requests containing the following elements:
*An HTTP method. One of GET, POST, PUT, or DELETE.
*A resource identifier.
*One or more parameters. For a GET request, query parameters, or for any other request, a correctly formatted input object.
Actuate REST API summary
Table 15‑3 lists the REST API resources and the operations associated with the HTTP methods used by each resource.
Table 15‑3 REST API resource and method quick reference
Resource
Supported HTTP Methods
Description
login
POST
Returns an authentication identifier and an authentication token
folders
GET, POST
Returns a list of folders or creates a new folder
folders/<folderId>
GET, DELETE, PUT
Accesses or changes a specific folder
folders/<folderId>/items
GET
Accesses the complete contents of a specific folder
folders/<folderId>
/privileges
GET, POST
Accesses or changes folder privileges
files
GET
Returns a list of files
files/<fileId>
GET, DELETE, PUT
Accesses or changes a specific file
files/<fileId>/download
GET
Downloads a file from the volume
files/<fileId>/privileges
GET, POST
Accesses or changes file privileges
files/<file>/upload
POST
Uploads a file to the volume
visuals/<visualId>
/bookmarks
GET
Returns a list of bookmarks from a specific report file
visuals/<visualId>
/bookmarks
/<bookmarkName>
GET
Returns the contents of a report document referenced by a bookmark
visuals/<visualId>/datasets
GET
Returns the list of data sets from a report document file
visuals/<visualId>
/datasets/<datasetName>
GET
Returns the contents of a specific data set from a report document file
visuals/<visualId>/execute
POST
Runs a report immediately and creates a transient document
visuals/<visualId>
/schedule/now
POST
Runs a report design and saves the document
visuals/<visualId>
/schedule/once
POST
Creates a schedule to run a job once
visuals/<visualId>
/schedule/recurring
POST
Creates a recurring schedule of jobs
visuals/<visualId>
/parameters
GET
Returns the list of parameters from a specific report executable file
visuals/<visualId>
/parameters/picklist
GET
Returns the picklist for a parameter from a specific report executable file
visuals/<visualId>/pdf
GET
Returns a page range from a report in PDF format
visuals/<visualId>/xlsx
GET
Returns a page range from a report in Excel format
jobs
GET
Returns a list of jobs
jobs/<jobId>/status
GET
Returns the status for a job or schedule
jobs/<jobId>
DELETE
Removes a job or schedule
dataobject/<dataobjectId>
GET
Returns the list of data sets from a BIRT data object
dataobject/<dataobjectId>
/<datasetName>
GET
Accesses a data set from a BIRT data object
users
GET, POST
Returns a list of users or creates a user
users/<userId>
GET, DELETE, PUT
Accesses or changes a specific user
users/<userId>/usergroups
GET
Returns list of user groups to which a user belongs
usergroups
GET, POST
Accesses user groups or creates a new user group
usergroups/<groupId>
GET, DELETE, PUT
Accesses or changes a specific user group
usergroups/<groupId>
/users
GET
Returns the list of users that belong to a user group
The following sections provide an overview of each set of resources and an example of using each resource as a curl command. The curl examples use Windows-format system variables for the REST API host server and the authentication identifier, AuthId. To use these examples on a Linux system, change the %variable% format to $variable. The curl examples demonstrate the use of the HTTP header for the authentication identifier. To use the ‑‑user parameter in the curl command, append a colon (:) character to the AuthId value.
Actuate REST API syntax
The first part of a REST API URI consists of the web server, context root, and port number of the REST server. The default web server is the machine on which BIRT iHub is installed. The default port is 5000. To create an HTTPS request, use port 5010. The second part of a REST URI has the following syntax:
/ihub/v1/<resource>[/{identifier}][/<subresource>]
[?<parameter=value>{&<parameter=value>}]
*/ihub/v1 is the default context root and directory for REST API resources.
*<resource> is the name of the REST API resource.
*{identifier} is a parameter to a branch in the REST API resource.
*<subresource> is the name of a branch in the REST API resource.
*<parameter=value> specifies the parameters and values that a GET request requires.
REST principles support branches from a parent resource. REST requests in a branch in the hierarchy require input parameters in the URI. The resource syntax shows the input parameters inside braces ({ }). A REST resource uses name-value pairs separated by an equal sign for any additional parameters. Depending on the resource, use either the URI or JSON-formatted objects in the body of the request to provide optional parameter values.