The REST Web API allows an external application to access the information stored in the Unity iQ database.

The end point of the API is http(s)://unityiqserver:port/api/rest/{controller} where controller can be "services" or "cis".

In this first release the API will only support the creation, list, update and delete of services, configuration items related to them and incidents.

The API are fuly RESTful, that means that in order to interact with Unity iQ the user must use different http verbs to list, create, update and delete.

The HTTP VERBS supported are GET (list), POST (Create), PUT (Update), DELETE (Delete)

The API response is a JSON string with the following format:


{ version: "1.0", errors:[], data:[]}


where Version is the Web Api version, Errors contains the error messages and data contains the information returned.


AUTHENTICATION


In order to use the Web API, the user must use an API Key in the form of a GUID.

The API Key is linked to a permission group that must have administrative rights. To get the API Key at the moment the user must go to the permissiongroups table in the database and copy the permissionguid.


The user must add to the request the Header Key X-ApiKey with value the permissionguid.

In case of absence of the Header or wrong key the API will return an unauthorized response.


SERVICES

The end points for the services controller are:

End Point Description HTTP Verb Request Response
http(s)://unityiqserver:port/api/rest/services list of all services GET
The result is a IQueryable list of services in JSON format with perspectives associated that can be filtered using the OData query syntax
http://www.odata.org/getting-started/basic-tutorial/
http(s)://unityiqserver:port/api/rest/services/{id} Returns the service with the service id specified GET The id of the service The result is the representation of the Service in JSON format, with the perspectives associated to it . If the Id does not specify any service an empty object is returned
http(s)://unityiqserver:port/api/rest/services Returns the new service with the service Id assigned by Unity iQ POST In order to create the new service, the user must provide name and description in JSON format in the body of the request:
{"name":"web api service", "description":"web api service description"}
name is a mandatory field.

Returns the new service and perspectives associated with the service Id assigned by Unity iQ.
If case the name is null or empty, an error will be generated. All the error and exceptions will be encapsulated in the errors field.
http(s)://unityiqserver:port/api/rest/services/{id} Update Name and Description fields for service with id {id} PUT The user must provide id, and name and description in JSON format in the body of the request:
{"name":"web api service", "description":"web api service description"}
The result is the representation of the updated Service in JSON format, with the perspectives associated to it.
http(s)://unityiqserver:port/api/rest/services/{id} Delete Service with id {id} DELETE The id of the service A message confirming that the service was deleted.


CONFIGURATION ITEMS


 End Point Description HTTP Verb Request Response
http(s)://unityiqserver:port/api/rest/cis list of all configuration items GET
The result is a IQueryable list of configuration items in JSON format that can be filtered using the OData query syntax
http://www.odata.org/getting-started/basic-tutorial/
http(s)://unityiqserver:port/api/rest/cis/service/{service id}/{perspective name} list of all configuration items belonging to perspective {perspective name} of service with id {service id} GET The service id and the perspective name (application, enduser, infrastructure) The result is a IQueryable list of configuration items in JSON format that can be filtered using the OData query syntax.
If the service id does not match any service or the perspective name is different from application, enduser or infrastructure, then a no found result is returned.
http(s)://unityiqserver:port/api/rest/cis/{id} Returns the configuration item with the configuration item id specified GET The id of the configuration item The result is the representation of the configuration item in JSON format. If the Id does not specify any configuration item, an empty object is returned
http(s)://unityiqserver:port/api/rest/cis/service/{service id}/{perspective name} Create a new configuration item with the configuration item Id assigned by Unity iQ POST The user must provide the service id, and the perspective name in the url. The user must also provide name (mandatory), source (optional, it is used to generate the objectkey in case of multiple monitoring systems), path (mandatory), classtype (optional) and url (optional) in JSON format in the body of the request:
{"name":"web api service", "source":"source of the configuration item", "path":"path/to/ci", "classtype":"web-api-class","url":"http://url.to/ci"}
In case the path is not present, it will be generated using the name of the CI.
Returns the new configuration item associated with the service and perspective.
If case the name is null or empty, an error will be generated. All errors and exceptions will be encapsulated in the errors field.
http(s)://unityiqserver:port/api/rest/cis/{id} Update fields for configuration item with id {id} PUT The user must provide the configuration item id in the url. The user has also to provide name, path, classtype, url, healthstate and rawhealthstate in JSON format in the body of the request:
{"name":"web api service", "path":"path/to/ci", "classtype":"web-api-class","url":"http://url.to/ci", "healthstate":"Healthy", "rawhealthstate":"raw health state"}
The healthstate value must match one of the HealthState Enum values (Unknown, NotMonitored, inMaintenance, Healthy, UnHealthyWarning, UnHealthyCritical or UnReachable)
The result is the representation of the updated configuration item in JSON format.
http(s)://unityiqserver:port/api/rest/cis/service/{service id}/{perspective name}/{ci id} Delete configuration item with id {ci id} associated to service with id {service id} and perspective name {application, enduser, infrastructure} DELETE The id of the configuration item, the service id and the perspective name (application, enduser, infrastructure) A message confirming that the configuration item was deleted.


INCIDENTS


  End Point Description HTTP Verb Request Response
http(s)://unityiqserver:port/api/rest/incidents list of all incidents GET
The result is a IQueryable list of incidents in JSON format that can be filtered using the OData query syntax
http://www.odata.org/getting-started/basic-tutorial/
http(s)://unityiqserver:port/api/rest/incidents/service/{service id} list of all incidents belonging to service with id {service id} GET The service id The result is a IQueryable list of configuration items in JSON format that can be filtered using the OData query syntax.
If the service id does not match any service, then a no found result is returned.
http(s)://unityiqserver:port/api/rest/incidents/{id} Returns the incident with the id specified GET The id of the incident The result is the representation of the incident in JSON format. If the Id does not specify any incident, an empty object is returned
http(s)://unityiqserver:port/api/rest/incidents/service/{service id} Create a new incident with the Id assigned by Unity iQ POST Properties to provide in JSON format in the body of the request:
Property Type Mandatory Description
Name string yes Incident name
Description string

IncidentPriority string

Priority int

ShortDescription string

State string

AssignedTo string

Category string

RelatedCI string

incidentState Enumeration(New, Closed,
Pending, Active, Resolved)


IncidentUrgency Enumeration(High, Medium,Low)

IncidentImpact Enumeration(High, Medium,Low)


Example:
{"name":"Incident", "description":"incident description", "incidentpriority": "Medium", "incidentImpact": "High", "assignedto":"Assignee", "state":"string", "category":"incident", "relatedci":"ci", "shortdescription":"description"}
Returns a new incident associated with the service. If case the name is null or empty, an error will be generated. All errors and exceptions will be encapsulated in the errors field.
http(s)://unityiqserver:port/api/rest/incidents/{id} Update Incident PUT Same as above The updated incident.
http(s)://unityiqserver:port/api/rest/incidents/service/{service id}/{incident id}  Delete incident with id {incident id} associated to service with id {service id} DELETE The id of the incident and the service id A message confirming that the incident was deleted.


ALERTS


End point Description HTTP Verb Request Response
http(s)://unityiqserver:port/api/rest/alerts list of all alerts GET
The result is a IQueryable list of alerts in JSON format that can be filtered using the OData query syntax
http://www.odata.org/getting-started/basic-tutorial/
http(s)://unityiqserver:port/api/rest/alerts/service/{service id} list of all alerts belonging to service with id {service id} GET The service id The result is a IQueryable list of configuration items in JSON format that can be filtered using the OData query syntax.
If the service id does not match any service, then a no found result is returned.
http(s)://unityiqserver:port/api/rest/alerts/{id} Returns the alert with the id specified GET The id of the alert The result is the representation of the alert in JSON format. If the Id does not specify any alert , an empty object is returned
http(s)://unityiqserver:port/api/rest/alerts/service/{service id} Create a new alert with the Id assigned by Unity iQ POST Properties to provide in JSON format in the body of the request:
Property Type Mandatory Description
Message string yes alert message
Source string yes alert source
Severity Enumeration(Information, Warning, Critical, Failure, Debug)

ResolutionState Enumeration(Open, Closed, OnHold, ConfirmationRequired, Reopened, Resolved)

ConfigurationItemId int
confirmation item id

Example:
{"message":"message description", "source":"source of the alert", "Severity": "Critical", "ResolutionState": "Open"}
The new alert with the id generated by the system
http(s)://unityiqserver:port/api/rest/alerts/{id} Update Alert PUT Same as above The updated alert.
http(s)://unityiqserver:port/api/rest/alerts/service/{service id}/{alert id}  Delete alert with id {alert id} associated to service with id {service id} DELETE The id of the alert and the service id A message confirming that the alert was deleted.