REST API Reference

When KeyReporter is running as part of a KeyServer service it exposes a REST API for accessing the objects on KeyServer. This API can be used to manage saved reports and report templates, and also gives view and modify access to Computers, Policies, Products, and other objects.

This document provides information on the REST methods and resources for version 2 of the API (available in KeyServer version 7.4.1.0 and higher). The API should be used for basic querying of the data, and not for bulk or heavy-use data retrieval. There are currently other more efficient mechanisms for processes that require full data capture or continual bulk data access.

The easiest way to test the API is to use a program like curl, although for GET-based methods a browser will be sufficient. Tools like Postman are useful for more advanced API testing.

Authentication

Before accessing most of the resources available through the API, you must provide authentication credentials — typically a KeyServer administrator account name and password. The easiest way to do this is by using the HTTP Basic auth header, sent via a secure connection (HTTPS).

For example, if you use curl to access the API, the following (partial) command will provide authentication via the HTTP Basic method:

curl --user name:password https://server.sample.net/api/v2/...

If you are using a browser to test the API, or if you access the API using JavaScript in a browser, the authentication process is streamlined using cookies.

URI Pattern and the Resource Hierarchy

All REST APIs are intended to provide access to resources using predictable and consistent URIs. Clients of a REST API submit HTTP requests and receive the results of the request in well-defined formats. Each request operates on the specified resource according to the request's HTTP method, which can be one of GET, PUT, POST, PATCH, and DELETE. A REST API request URI follows the pattern:

https://server.sample.net/api/v2/resource-path?arguments

The resource-path gives the path to a unique resource. Requests can be made on resources at each level of the hierarchy, and the response will list the resources contained at that level. For example, a request made for the URI:

https://server.sample.net/api/v2

would return the resources available within version 2 of the API:

[
	{ "ident":"computer", "type":"topic" },
	{ "ident":"map", "type":"topic" },
	{ "ident":"policy", "type":"topic" },
	{ "ident":"product", "type":"topic" },
	{ "ident":"program", "type":"topic" },
	{ "ident":"purchase", "type":"topic" },
	{ "ident":"report", "type":"topic" },
	{ "ident":"sql", "type":"topic" },
	{ "ident":"user", "type":"topic" }
]

When a request is made for a resource that is not a container, the response has just the single resource.

The arguments in the URI can supply:

  • a filter for selecting resources
  • a list of fields that should be returned in the response
  • other directives specific to the request
Filters and field lists are covered below.

Request & Response Formats

When POSTing data, the format can be XML or JSON. The type will be auto-detected, but to remove ambiguity and the chance of error, the request should include a Content-Type header that indicates the actual format used. With curl you can do this as follows:

curl --header "Content-Type: application/json" https://server.sample.net/api/v2/...
curl --header "Content-Type: application/xml" https://server.sample.net/api/v2/...

Responses will be formatted as JSON by default. It is also possible to get responses formatted as XML by including a "Accept: application/xml" header in the request. With curl you can do this with the --header option:

curl --header "Accept: application/xml" https://server.sample.net/api/v2/...

If you are using a browser to test the API the responses will be JSON. With JavaScript and other environments there are ways to set request headers in order to specify the request and response formats.

JSON Schema
Responses with Content-Type "application/json" conform to a simple schema that supports individual objects and arrays of objects, where each object contains properties corresponding to the requested fields in addition to the resource ID and type.

XML Schema
Responses with Content-Type "application/xml" conform to a simple schema that supports individual items and lists of items, where each item can optionally contain a number of fields.

Response Fields

Response data contains the resource ID and type by default. To receive other attributes of the resource, the attribute field names are given in the fields argument. Field names vary depending on the resource type, but all resources have ident and type fields. The ident can be used to request resources within the requested resource.

https://server.sample.net/api/v2/computer

This query would return a response with all the sub-resource within the computer resource:

[
	{ "ident":"items", "type":"topic" },
	{ "ident":"sections", "type":"topic" },
	{ "ident":"divisions", "type":"topic" },
	{ "ident":"schema", "type":"topic" }
]

The list in the response gives resources that we can request within the computer resource.

For resources that do not contain other resources, the response will be a single object instead of a list of objects. In the next example we also include a fields argument, with field names separated by commas. The fields are specific to the resource type, product in this case:

https://server.sample.net/api/v2/product/items/5A55ADEF383F4E8798073862A18D3433?fields=Name,Version,Publisher

When a URI includes a fields argument, the those fields will be included in the resource record (the ident and type fields are always included):

{
	"ident": "5A55ADEF383F4E8798073862A18D3433"
	"type": "product"
	"Name": "Microsoft Office 2008 for Mac Standard Edition",
	"Version": "2008",
	"Publisher": "Microsoft Corporation"
}

Valid field names for each resource type can be retrieved from the associated schema resource, described below.

Filtering

https://server.sample.net/api/v2/product/items?query=(publisher='Bare%20Bones%20Software,%20Inc.')
[
	{ "ident":"5A55ADEF475E4E37BDF43D603E676C57", "type":"product" },
	{ "ident":"5A55ADEF92D6406BAFD35FF82EBDA294", "type":"product" },
	{ "ident":"5A55ADEFB3C743F4AFF1096DCE388A58", "type":"product" },
	{ "ident":"5A55ADEFBA2EB011E528102AF82C4017", "type":"product" },
	{ "ident":"5A55ADEFBA2EB011E528102AF82C4019", "type":"product" },
	{ "ident":"5A55ADEFBA2EB011E528102AF82C401A", "type":"product" },
	{ "ident":"5A55ADEFBA2EB011E528102AF82C401B", "type":"product" }
]

Schema resources

https://server.sample.net/api/v2/product/schema/folders
{
	"columns": [
		{
			"ident":"name",
			"type":"column",
			"name":"Name",
			"readonly":0
		},
		{
			"ident":"flag",
			"type":"column",
			"name":"Flags",
			"readonly":0
		},
		{
			"ident":"colr",
			"type":"column",
			"name":"Color",
			"readonly":0
		},
		...
	]
}

Resources

/api/v2

GET
Return the list of resources available in version 2 of the API

/api/v2/object-type

GET
Return the list of resources for the given object type.

/api/v2/object-type/items

GET
Return a list of items of the given object type.
POST
Create an item of the given object type.
DELETE
Delete one or more items of the given object type.

/api/v2/object-type/{folders, divisions, sections}

GET
Return a list of folders for the given object type.
POST
Create a folder for the given object type.

/api/v2/object-type/schema

GET
Return the list of schemas available for the given object type.

/api/v2/object-type/items/resource-id

GET
Return the resource of the given type and ID.

/api/v2/object-type/{folders, divisions, sections}/resource-id

GET
Return the resource of the given type and ID.

/api/v2/object-type/schema/items

GET
Return the schema for items of the given object type.

/api/v2/object-type/schema/{folders, divisions, sections}

GET
Return the schema for folders for the given object type.

/api/v2/report

GET
Return the list of resources related to reports on KeyReporter.

/api/v2/report/items

GET
Return the list of saved reports on KeyReporter.
POST
Submit a request for a new report to be created based on the suppied parameters.
DELETE
Delete one or more saved reports.

/api/v2/report/folders

GET
Return the list of report folders on KeyReporter.
POST
Create one or more new report folders
DELETE
Delete one or more report folders

/api/v2/report/templates

GET
Returns the list of report templates on KeyReporter.
POST
Create one or more new report templates
DELETE
Delete one or more report templates

/api/v2/report/schema

GET
Return the list of schemas available for report resources

/api/v2/report/items/resource-id

GET
Returns the properties of the report.

fields

name
text
The display name of this report.
moduleid
long
The unique ID of the report module that created this report.
category
text
The general category of this report.
author
text
The administrator who created this report.
folder
text
The folder that contains this report.
pname
text
The name of the parameter of this report.
ptype
text
The object type of the parameter of this report.
pdata
text
The object ID of the parameter of this report.
created
text
The date and time that this report was created.
range
text
An indication of the range of time on which this report ran.
start
text
The start date or the time range on which this report was run.
stop
text
The end date or the time range on which this report was run.
size
text
The site in bytes of this report.
runtime
text
The time in seconds that it took to generate this report.
notes
text
Custom notes added to this report by an admin.
To get the Name, Author, and Folder of a saved report:
https://server.sample.net/api/v2/report/items/5706a2fd-00000010.ksr?fields=name,author,folder
{
	"ident":"5706a2fd-00000010.ksr",
	"type":"ksr",
	"name":"Usage (VeraCrypt x comp)",
	"author":"caa_mam1061",
	"folder":"Lab Reports"
}
PATCH
Change properties of a saved report. Move report to a different folder.
DELETE
Delete a saved report

/api/v2/report/folders/resource-id

GET
Returns the properties of the folder.

fields

name
text
An encoding of the permissions for this folder.
perm
text
An encoding of the permissions for this folder.
To get the Name and Permissions of a folder:
https://server.sample.net/api/v2/report/folders/Shared?fields=name,perm
{
	"ident":"Shared",
	"type":"folder",
	"name":"Shared",
	"perm":"Administrator:adimv;KeyReporter Guest:iv;:"
}
PATCH
Change properties of a folder.
DELETE
Delete a folder

/api/v2/report/templates/resource-id

GET
Returns the properties of the template.

fields

name
text
The display name of this template.
moduleid
long
The unique ID of the report module that will run.
category
text
The general category of this template.
author
text
The administrator who created this template.
folder
text
The folder that contains this template.
pname
text
The name of the parameter of this template.
ptype
text
The object type of the parameter of this template.
pdata
text
The object ID of the parameter of this template.
range
text
An indication of the range of time on which this template will run.
notes
text
Custom notes added to this template by an admin.
To get the Name, Author, and Folder of a template:
https://server.sample.net/api/v2/report/templates/E6124C09BB704FB2AD01B00432AD2E3D?fields=name,author,folder
{
	"ident":"E6124C09BB704FB2AD01B00432AD2E3D",
	"type":"template",
	"name":"Product Optimizations (COMP x prod)",
	"author":"Administrator",
	"folder":"Management Reports"
}
PATCH
Change properties of a template.
DELETE
Delete a template

/api/v2/report/schema/{items, folders, templates}

GET
Return the schema for the given report resource

/api/v2/sql

GET
Return the list of resources related to running SQL queries.

/api/v2/sql/query

GET
Run an SQL query and receive result columns and rows.

/api/v2/sql/tables

GET
Return the list of tables that can be queried via SQL.

/api/v2/sql/tables/resource-id

GET
Return information on the columns of the given table.