RESTful Web Services API

Overview

Universal Controller supports a RESTful-based web services API that allows you to perform multiple operations, which are listed alphabetically on the following pages.

Formatting specifications for each web service, including details about field requirements, are provided.
 

Agents

Agent Clusters

Audits

Bundles and Promotion

Bundles

Promotion

Business Services

Calendars

Cluster Nodes

Connections

Credentials

Custom Days

Groups

Monitoring

OAuth Clients

OMS Servers

Passwords

Properties

Reports

Scripts

Server Operations

System

Task Instances

Tasks

Triggers

Universal Event

Universal Event Templates

Universal Templates

Users

Variables

Virtual Resources

Workflow Task Instances

Workflow Tasks

Methods of API Operations

Every API operation is performed using one of the following methods.
 

Method

Description

GET

Retrieves records from the Controller database.

POST

Creates, or performs an action on, a record in the Controller database.

PUT

Modifies a record in the Controller database.
 

Note

PUT, by itself, actually replaces an existing record with whatever information you include in the PUT operation. If you include only partial record information in a PUT, the record in the database will then contain only that information.

In order to modify information in a record and retain all of its unmodified information, you must first GET the record from the database, modify (add/delete/change) information in the record, and then PUT the record back in the database.

DELETE

Deletes a record in the Controller database.

Authentication 

Universal Controller requires Web Service requests to be authenticated using one of Basic Authentication or Personal Access Token Authentication.

For Basic Authentication, use the following Authorization header, where the username:password is base64 encoded.

Authorization: Basic username:password

For Personal Access Token Authentication, use the following Authorization header.

Authorization: Bearer access-token

While it is recommended you use the Authorization header, if required, you can alternatively pass the Personal Access Token using the access_token query parameter.

http://hostname:port/uc/resources/task?access_token=access-token&taskname=MyTask

Request Limits

You can implement application- and user-level concurrent request limits to control how many web service API requests can be in progress at the same time via the following Universal Controller system properties:

Web Service Application Concurrent Request Limit

Controls the number of concurrent requests for the application (that is, the Universal Controller server).

This application-level concurrent request limit cannot be less than 1 or less than the user-level concurrent request limit (if specified).

Web Service User Concurrent Request Limit

Controls the number of concurrent requests per unique user ID.

This user-level concurrent request limit cannot be less than 1 or more than the application-level concurrent request limit (if specified).

If the application-level concurrent request limit is exceeded, an HTTP Status of 429 /Too Many Requests will be returned.

These properties are applied in the following order:

  1. User-level Concurrent Request Limit
  2. Application-level Concurrent Request Limit


Memory Utilization Threshold

You can specify a threshold for prohibiting access to the RESTful Web Service API based on a percentage of allocated memory in use.

Web Service Memory Utilization Threshold

Percentage of allocated memory in use that defines a threshold for prohibiting access to the RESTful Web Service API.

The threshold must be a whole number (integer) and cannot be less than 1 or more than 99.

If the threshold is exceeded, an HTTP Status of 503 /Service Unavailable will be returned.

Returned Messages

The following table identifies the status codes (part of the HTTP/1.1 standard) that can be returned.

Status Code

Description

200

Success

400

Bad request data.

401

User does not have authorization (password identification failure).

403

User does not have permission to access Web Services.
 
Access options are set via:

404

Resource not found.

429Too Many Requests.

500

All other errors.
 
For List Variables, 500 is returned if the Web Service fails due to invalid parameters. (A status description also is returned.)

503Service Unavailable.

Any other failure status codes may be returned by the underlying RESTful services. Most resources (Controller records) are returned as XML.

You can check status codes in the Audits and the uc.log file to determine the cause if their Web Service client is not displaying the error message that comes back with the response.

User Restriction

You can be restricted from logging in to the RESTful Web Services API either of two ways:

  1. The system level default for RESTful Web Services API access, specified by the System Default Web Service Access Universal Controller system property, has been set to No, and the Web Service Access field in the User Details for your user account is set to -- System Default --."
  2. The Web Service Access field is set to No, which overrides the System Default Web Service Access value.

If either restriction is in place, the following error message will be written to the Audits table and the opswise.log file when you attempt to access the RESTful Web Services API:

User <your user name> not permitted to use Web Services. Please check with your administrator.

To remove the restriction, the system administrator must either:

  • Set the System Default Web Service Access property to Yes and set the Web Service access field on the User Definition screen for your user account to -- System Default --.
  • Set the Web Service access field on the User Definition screen for your user account to Yes.

Password Expiration

While a password is expired, RESTful Web Services API access will be prohibited until the password has been changed.

Note

Password expiration is not applicable to LDAP authenticated users.