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.
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:
- User-level Concurrent Request Limit
- 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.
|
404 | Resource not found. |
429 | Too Many Requests. |
500 | All other errors. |
503 | Service 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:
- 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 --."
- 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.