This page reviews the RESTful API for GroundWork Monitor.
WAS THIS PAGE HELPFUL?
REST (REpresentional State Transfer) is a distributed computing style based on the architectural successes of the web. The RESTful Services for GroundWork Monitor are a set of distributed web service APIs adhering to the design principles of REST. In REST terminology, a web service API is known as a resource.
The foundation web services are based on the following REST principals:
By applying web and HTTP principles to web services, web services will gain some of the desirable properties of the web such as horizontal scalability, decoupled clients and servers, reduced latency through the use of proxies and real interoperability.
Another very real feature of RESTful APIs are their simplicity and familiarity of use. With any RESTful API, it should be relatively trivial to point a simple client (e.g. curl in a shell script) at a URI for the API and quickly build something useful. This makes a refreshing change from heavyweight middleware frameworks such as CORBA or WS-*.
The following convention applies to all REST services for the foundation unless otherwise noted on the separate service.
Only standard HTTP methods are supported:
Not supported in the initial release. Support can easily be added, but may require changes in the Collage database to support last modified date on all resources. If supported the REST API would return a 304 code for resource requests that have not changed with an empty body.
Objects are created using the HTTP Post Method. Parameters should be supplied in the request body as a JSON or XML. Successfully creating or updating a resource will result in a 200 HTTP status code.
All XML post data will follow the general pattern of a plural collection name, and repeated individual singular elements, for example:
And for JSON:
Some APIs support the creation of objects asynchronously with the HTTP Post Method. The default is to create them synchronously. To override this behavior and create the objects asynchronously, pass in the async request parameter:
A synchronous (default) request will not return back to your client code until the completion of processing all objects provided in the post data. Whereas an asynchronous request will submit the work to a queue, and return immediately.
Successfully submitting the request will result in a 200 HTTP status code. Failure to submit to the request will return a 500 HTTP Status Code.
Objects are deleted using the HTTP Delete Method. Parameters should be supplied in the request body as a JSON or XML. Successfully deleting a resource will result in a 200 HTTP status code.
All XML post data for deletions will follow the same pattern as for creates, with the exception that only the objects primary key(s) are required: all other fields are ignored.
And for JSON:
Objects can also be deleted by passing comma-separated (and encoded) primary keys on the path:
Any request may result in one of the following error codes:
When error codes are sent, XML, JSON, or HTML content is also sent to describe the error. The specific representation sent is based on the content type accepted by the request, (i.e. the Accept header). Here are examples of XML and JSON content:
JSON Bad Authorization Token, (401 Unauthorized)
XML Host Not Found, (404 Not Found)
XML Invalid API Endpoint, (404 Not Found)
JSON Invalid Hosts Query String, (500 Internal Server Error)
HTML content is sent when the URL does not resolve to any REST API service or the endpoint is invoked from the browser where any content type is accepted.
All dates returned by the Rest API will be in ISO-8601 Extended Combined Date and Time format:
YYYY = Year
MM = Month
DD = Day
HH = hour
mm = minute
ss = second
SSS = millisecond
ZZZZZZ = Timezone in format of 6 required characters: ±HH:mm
± either plus (+) or minus (-) to represent the UTC offset from UTC (Coordinated Universal Time (GMT))
HH (hour) mm(minute) format
GMT time would be +00:00 (zero hour, zero minute offset from UTC; the ’Zulu’ form will not be returned)
Dates provided in POST data must also be formatted in one of the following formats:
Some APIs allow for shallow, deep, or other representations of entities. Shallow representation retrieves only the primitive data attributes (of an entity (i.e. Host, Device), and the properties of that entity. Deep representations will take longer to retrieve, since objects need to joined from the database to bring together all associated collections and 1:1 associations.
|shallow||primitive data attributes, 1:1 association names, properties (default)|
|deep||shallow, plus: associated collections (shallow), 1:1 associations shallow|
|simple||Same as shallow except there are no properties (only supported for Hosts)|
|full||recursive form of deep where collections and associations are also retrieved deep, (only supported for Categories)|
|sync||special depth used when synchronizing entities with external systems, (only supported for Hosts and Services)|
Mapping depth is provided as a query parameter named "depth". Valid values are "shallow", "simple", "deep", "full", and "sync". Not all entities support the depth parameter. The following entities do support depth:
If a depth query parameter is not provided, the default is Shallow.
The HTTP response depends on the type of operation. There are three general types of responses:
When looking up by primary key, GET operations return a single entity. All other GET operations like queries, will return a collection of one or more entities, wrapped by a container element. GET operation responses are dependent on the HTTP code. Your code should always check the HTTP status code prior to looking at the HTTP response:
Examples of GETs
A primary key GET will return a single <host> element:
Queries return collections of entities for example:
The HTTP response for POST, PUT and DELETE operations return a <results> collection of one or more <result> elements. For POST, PUT and DELETE operations, the server tries to return 200, with detailed response codes for each individual operation. Thus these kind of CRUD operations are not transactional. For example, if your application posts 3 host entities, 2 might succeed, and one update might fail.
Your code should always check the HTTP status code prior to looking at the HTTP response:
The results element has the following attributes:
The result element has several attributes:
Queries are specified as the WHERE clause of a query only. The column names in queries must map to Collage entity model names, not database columns. The actual names valid in queries are included in this document. Valid names are specific to which entity you are querying i.e. Host, Event, Service... .
A simple query
hostName = ‘localhost’
Queries can be anded or or-ed:
(device = ‘localhost’ and severity = ‘FATAL’)
Parenthesis are supported to group expressions:
((device = ‘localhost’ and severity = ‘FATAL’) and (msgCount > 3))
Standards operators supported =, <>, >, <, like, between, in
property.ExecutionTime between 500 and 1000
(appType = 'NAGIOS' and device like '172.28.113%')";
Properties are prefixed by the prefix "property.":
(property.ExecutionTime < 10 and property.Latency between 800 and 900)
Queries can be sorted using the order by clause. Queries can be sorted on properties:
(property.ExecutionTime < 10 and property.Latency between 800 and 900) order by property. Latency
Date Range queries are supported:
property.LastStateChange > '2013-05-17 09:33:00'
(property.LastStateChange between '2013-05-20' and '2013-05-22') and monitorStatus = 'UP'
Functions are supported in queries:
day(property.LastStateChange) = 18
Not null checks syntax:
(appType is not null)
In Queries are supported:
host in ('qa-load-xp-1','qa-sles-11-64','do-win7-1')
However, IN clauses must not have spaces
|Date Functions||day, month, year, hour, minute, current_date|
Functions Not Supported
|Aggregate Functions||sum, count, avg, min, max|
By default, all queries will return the entire result set. There are two request parameters supported by all queryable REST APIs:
|first||Query||Paging. First record to start from|
|count||Query||Paging. Number of records to include when paging|
These two parameters are optional. If they are not specified, no paging will occur and the entire result set will be return.
Using the paging parameters requires the client application to track the page counts. If your application wanted to present pages the results of a query in pageable format, the API call should specify a "first" parameter and a “count” parameter. These two parameters define the window of paging over a query.
A first request should set first=1, and count should be set to the number of records returned. For example, here is a first request, asking for 20 items:
A second request would retrieve items 21-40
And so on...
The GroundWork REST API has a set of APIs that closely mirror the entities in the GroundWork database. An entity is simply a class of objects in GroundWork’s data model. In the database, they are represented as tables. All entities in the GroundWork database have a base set of standard attributes. These attributes can be retrieved, queried, and stored onto entities at run time. When querying the REST API, you will always get back an object’s base attributes.
Additionally, some of the entity types have dynamic properties. These dynamic properties can be user-defined. By default, an entity will not have any dynamic properties. However applications, including internal GroundWork applications, can add dynamic properties to entities at run time. Through the Rest API, dynamic properties can be easily created with the PropertyType API, and then attached to entities that support dynamic properties. When retrieving entities that support dynamic properties, these properties are automatically returned in a properties map.
The following APIs support Dynamic Properties:
Out of the box, there are a set of Dynamic Property Types:
|Alias||Host Alias information||String|
|CactiRRDCommand||Cacti RRD Command||String|
|Category||Category of snmp device||String|
|Comments||Host or Service Comments in XML format||String|
|ContactNumber||Last output received||String|
|ContactPerson||Last output received||String|
|CurrentAttempt||Current attempt running check||Long|
|CurrentNotificationNumber||The count of notifications||Integer|
|DeactivationTime||The time when the host was deactivated||String|
|Event_OID_symbolic||Event_OID_symbolic of snmp device||String|
|LastNotificationTime||The time of the last notification||Date|
|LastPluginOutput||Last output received||String|
|LastStateChange||The time of the last change of state||Date|
|Location||Last output received||String|
|MaxAttempts||Max attempts configured||Long|
|Notes||Configuration Notes field||String|
|Parent||List of parent hosts separated by commas||String|
|PerformanceData||The last Nagios performance data||String|
|RRDCommand||Custom RRD command||String|
|RRDLabel||Label for Graph||String|
|RRDPath||fully qualified path to RRD image||String|
|RemoteRRDCommand||Remote RRD Command||String|
|RetryNumber||The number of times an attempt has been made to contact the service||Integer|
|TimeCritical||The amount of time that the entity has had a status of CRITICAL||Long|
|TimeDown||The amount of time that the host has been DOWN||Long|
|TimeOK||The amount of time that the entity has had a status of OK||Long|
|TimeUnknown||The amount of time that the entity has had a status of UNKNOWN||Long|
|TimeUnreachable||The amount of time that the host has been UNREACHABLE||Long|
|TimeUp||The amount of time that the host has been UP||Long|
|TimeWarning||The amount of time that the entity has had a status of WARNING||Long|
|ipaddress||ip Address of snmp device||String|
|isAcknowledged||Has the current state been acknowledged?||Boolean|
Queries on dynamic properties are prefixed by "property." For example:
GET /api/services?query=property.LastPluginOutput like ‘OK%’
In responses, properties are included in a property map. For example:
In versions 7.0.0 through 7.0.1 of the GroundWork Rest API, all APIs were protected by HTTP Basic Authentication. Every request you made to this web service must provide HTTP Authentication headers. Starting with version 7.0.2, the Rest API has discontinued support of HTTP Basic Authentication.
With version 7.0.2 onwards, Token-based Authentication is required. Token-based Authentication introduces a new, optimized authentication algorithm that will greatly optimize and improve the performance of the Rest APIs. Instead of requiring authentication with each and every request, authentication is only required once, to retrieve a token. This trusted token can then be used on all subsequent API calls to authorize the requesting application access to protected resources. This token must be passed with each request as an HTTP header.
A token is on valid for a configured lifetime. The duration of this lifetime defaults to 8 hours. When making an API call, it is possible that the token can expire. In this case, your application will need to handle re-authentication with credentials. Note that our Java and Perl Client APIs will handle this for you automatically.
Before making any API requests, you must first make an authentication request. Authentication is achieved by call the /auth/login API with encoded and/or encrypted credentials:
curl -i -X POST -d "user=d3N1c2Vy&password=d3N1c2Vy&gwos-app-name=cloudhub" http://localhost/api/auth/login
The user must always be Base64 encoded. If security encryption is enabled, the encrypted password should be passed without additional encoding; otherwise, unencrypted passwords must be Base64 encoded. If authentication succeeds, a 200 response code is returned along with a single token in the response. This token must be passed on to all subsequent calls in the GWOS-API-TOKEN HTTP header:
curl -H "Accept: application/xml" -H "GWOS-API-TOKEN:24528E5E970AFEC8D1E887DD9CA2C825" -H "GWOS-APP-NAME:cloudhub" http://localhost:8080/foundation-webapp/api/categories
An additional APP-NAME HTTP header is required. To summarize, all API calls (except auth/login) will always require two HTTP headers:
GWOS-API-TOKEN - the token return by /api/auth/login
GWOS-APP-NAME - identify your application with this header
When a token expires, applications will need to handle this exception. A request with an expired token will return an HTTP Status Code 401 Unauthorized.
|Note that our Java and Perl Client APIs will handle re-authentication for you automatically.|
When this happens, your application will need to re-authenticate with the /api/auth/login API retrieving a new token. With this new token in the HTTP header GWOS-API-TOKEN, you can then resubmit your request.
See the Auth APIs in the RESTful Services section for more details.