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:

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:

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

Request & Response Formats

When POSTing data, the format can be XML, JSON, and in some cases plain text. The type will be auto-detected, but to remove ambiguity and the chance of error, XML or JSON requests 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.

When the response contains multiple resources, the resources are sent as members of a JSON array.

[
	{ resource fields... },
	{ resource fields... },
	...
]

Responses with just one resource are sent without an enclosing array.

{
	resource fields...
}

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.

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:

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

[
	{ "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" }
]

Schemas

{
	"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

{
	"ident":"5706a2fd-00000010.ksr",
	"type":"ksr",
	"name":"Usage (VeraCrypt x comp)",
	"author":"caa_mam1061",
	"folder":"Lab Reports"
}

{
	"ident":"Shared",
	"type":"folder",
	"name":"Shared",
	"perm":"Administrator:adimv;KeyReporter Guest:iv;:"
}

{
	"ident":"E6124C09BB704FB2AD01B00432AD2E3D",
	"type":"template",
	"name":"Product Optimizations (COMP x prod)",
	"author":"Administrator",
	"folder":"Management Reports"
}