Request URLs

Request URLs can be in any of the following forms. These examples assume vovserver is listening on port 2345 of a machine named myserver.

Form 1: Querying for All Fields of an Object

http://myserver:2345/api/v3/jobs/12345
http://myserver:2345/api/v3/jobs/12345/
http://myserver:2345/api/v3/jobs/12345/*

The v3 part of the API refers to the current API revision. Old API revisions will continue to be supported as new revisions are introduced, e.g. when the current revision is 4, the v3 URLs will remain functional.

All of the above URL formats are identical in behavior and output, and will return a formatted list of all fields in job 12345. This is equivalent to vovselect '*' from jobs where idint==12345 in the CLI.

Form 2: Querying for a Specific Field

http://myserver:2345/api/v3/jobs/12345/status

This form will return a single field (status) from job 12345. This is equivalent to vovselect status from jobs where idint==12345. The output will be similar to:

{"startrow":1,"endrow":1,"query":"SELECT status FROM jobs WHERE idint==1158062","errormsg":"","columns":[{"col":0,"field":"status"}], "rows":[["VALID"]]}

Form 3: Perform a Complex Query

http://myserver:2345/api/v3/query?select=idint,host,status&from=jobs&where=status%3d%3dVALID&limit=10&order=host%20DESC

This form allows complex SQL-style queries (note that characters such as space and "=" must be URL encoded). The where clause contains Selection Rules, which filters the data set down to one or more specific objects. This above example is equivalent to

vovselect
                    idint,host,status -from jobs -where status==VALID -limit 10 -order "host
                    DESC".

The output will be similar to:

{"startrow":1,"endrow":8,"query":"SELECT idint,host,status FROM jobs 
WHERE status==VALID ORDERBY host DESC LIMIT 10","errormsg":"","columns":[{"col":0,"field":"idint"},
{"col":1,"field":"host"},{"col":2,"field":"status"}], "rows":[[1158051,"titanus","VALID"][1158058,
"titanus","VALID"][1158049,"skull","VALID"][1158062,"skull","VALID"][1158109,"skull","VALID"][1158117,
"skull","VALID"][1158101,"localhost","VALID"][1158105,"localhost","VALID"]]}

All forms allow the use of an additional format parameter in the URL to specify a format for the returned data. If no format is specified, the data are returned in JSON format. The following formats are currently supported:

Table 1.
Format	Description
json (default)	Return a JSON-formatted list of fields
csv	Return fields formatted as a CSV, with column headers
csv-noheader	Return fields formatted as a CSV with no column headers

For example the fields of job 12345 can be returned as a CSV list using the URL:

http://myserver:2345/api/v3/jobs/12345?format=csv

A complete list of fields, their data types, and the objects to which they belong can be viewed in Node Fields.