Resources & URIs

This section covers the available resources for the ScienceLogic API and information about creating and updating API resources.

Use the following menu options to navigate the SL1 user interface:

To view a pop-out list of menu options, click the menu icon ().
To view a page containing all of the menu options, click the Advanced menu icon ().

Available Resources

You can interact with the following entities through the API:

Accounts
Account Lockouts
Alerts
Appliances
Assets
Collector Groups
CBQoS Objects
Collection Labels
Credentials
Custom Attributes
Dashboards
Devices
Device Categories
Device Classes
Device Interfaces
Device Groups
Device Relationships
Device Templates
Discovery Sessions
Dynamic Applications
Events
Event Categories
External Contacts
File Uploads
Interfaces
Monitoring Policies
Organizations
Performance Data
PowerPacks
Product SKUs
Schedules
System Patches
System Settings
Tasks
System Thresholds
Themes
Thresholds
Tickets
Ticket Categories
Ticket Chargeback
Ticket Logs
Ticket Notes
Ticket Queues
Ticket States
User Policies
Vendors

Some resources support only view access to the corresponding SL1 entity, while other resources provide support for create, edit, and/or delete operations. For a full listing of all actions that can be performed through the API, see the Available Actions section.

URI Formatting

All resources have a URI relative to the base URI for the API:

For Database Servers, Administration Portals, and All-In-One Appliances, the base URI of the API is:

https://<ip-address or hostname of appliance>/api

The full URI for a resource has the following structure:

For the resource URIs listed in the previous section, the full URI of the index is:

The URIs for specific resources combine the resource index URI and the unique ID of the specific resource. For example, the URI for the ticket with ticket ID 1 is:

/ticket/1

Some resources include sub-resources. For example, a note is a sub-resource of a ticket. If a resource includes a sub-resource, each instance of that resource includes an index for the sub-resource. For example, the index of notes attached to the ticket with ticket ID 1 is:

/ticket/1/note

And the URI for a specific note attached to ticket 1 is:

/ticket/1/note/<note ID>

If you are accessing the API through an Administration Portal, Database Server, or All-In-One Appliance, the "/api" portion of the base URI is included in all resource URIs returned by the API.

Resource Index Responses

When you perform a GET request using the URI for a resource index, the response includes the following structure in JSON format:

{

"searchspec":{

"fields":{

"data":[

"field",

]

"options":{

"option name":{

"type":"...",

"description":"...",

"default":"...",

};

"total_matched":"X",

"total_returned":"Y",

"result_set":[

{

}

]

}

The XML response for the same request contains the same attributes in a similar structure.

The following sections are included in the response:

searchspec. Contains filters and options that you can add to the resource index URI.
total_matched. An integer that indicates the maximum number of resources the index could return in the result_set. Resources included in this count match the requested filters but might not be included in the response because of the specified options, or because a required option is missing.
total_returned. An integer that indicates the number of resources contained in the result_set.
result_set. Contains each specific resource that matches the filters included in the request URI.

Constructing URIs Using a searchspec

A GET request for a resource index responds with a "searchspec" section by default. The searchspec indicates the filters and options that can be added to a resource index URI to limit or change the results contained in the response. Filters and options are added to the URI as standard GET values:

Any number of options and filters can be added to the URI after the question mark (?), delimited by ampersands (&).

All resource indexes support an additional option that allows you to specify the sort order. The sort order option can be included only once in a single request.

Filters

You can filter the results contained in the response using any of the fields contained in the "fields" section of the searchspec. For basic equality operations, filters have the following syntax:

filter.<field name>=<value to equate>

You can add the following operators before the equals sign (=) to perform different comparisons:

.min. The specified value is the minimum value for the field. Equivalent to a "greater than or equal to" operation.
.max. The specified value is the maximum value for the field. Equivalent to a "less than or equal to" operation.
.contains. The field contains the specified value as a sub-string.
.begins_with. The field begins with the specified value as a sub-string.
.ends_with. The field ends with the specified value as a sub-string.
.isnull. The specified value must be 0 or 1. If you specify a value of 0, records that have a non-null value in the specified field will be returned. If you specify a value of 1, records that have a null (empty) value in the specified field will be returned.
.in. The field equates to one of the values given in a list. The value to equate must be in the following list format:

<value 1>, <value 2>, <value 3>, ...

For example, to request only tickets that have a severity of major or critical (severity > 3), add the following filter clause to the ticket URI:

filter.severity.min=3

The inverse of a filter can be created by adding ".not" to the filter clause. To request the inverse of the previous example:

filter.severity.not.min=3

If you include multiple filters for the same field in a URI, the API will return only results that match all the filters for that field (i.e. the API will perform an AND operation).

Options

Every resource index has a set of options that can be added to a request URI to limit or change the results contained in the response. Each entry in the "options" section of the searchspec has the following attributes:

type. The data type of the option value. The value you pass for this option must be of this data type.
description. A description of how the option affects the response.
default. The default value of the option.

The following options are available on most resource indexes:

extended_fetch. By default, the result_set will contain only the URI and description for each returned resource. If extended_fetch is set to 1 in the URI, the response will contain all attributes of all returned resources.
hide_filterinfo. If this option is set to 1 in the URI, the response will contain only the result_set.
limit. The maximum number of resources that should be returned in the response. For example, if you include "limit=100" in the URI, the first 100 resources are returned in the response.
offset. After the API has assembled a list of possible resources to include in the response, based on the specified filters, offset determines which resource will be the first entry in the response list. offset begins at zero for the first resource, one for the second resource, and so forth. For example, if you include "limit=5&offset=5" in the /ticket URI, the response contains tickets six through ten from the list of the possible tickets.
link_disp_field. If the extended_fetch option is not enabled, you can use the link_disp_field to specify which field will be used to populate the description for each resource. For example, the default description of each resource returned by the /account resource index is the username. If you want the description of each resource returned by the /account resource index to be the primary Email address of each user, set the link_disp_field option to email.

Although the above options are common to most resource indexes, not all resource indexes support all of these options.

Use the following syntax to specify an option:

For example, to request 10 tickets with all attributes returned from the ticketing index, use the following URI:

/ticket?limit=10&extended_fetch=1

Sorting

You can sort the order of results in the response by using the order option. This option is available for every resource index. The syntax of the order option is:

order.<field name>=<sort order>

Valid values for the sort order are:

ASC. Sort in ascending order.
DESC. Sort in descending order
<value 1>,<value 2>,<value 3>,..,*. Return the records that have value 1 as the value for the field first, then the records that have value 2 as that value for the field, etc. Any number of specific values can be specified, followed by an asterisk.
*,<value 1>,<value 2>,<value 3>,... Return all items that do not have one of the specified values as the value for the field, then return the records that have value 1 as the value for the field, then the records that have value 2 as that value for that field, etc. Any number of specific values can be specified.

For example, to sort the response for the /account resource by descending username, include the following option:

order.user=DESC

For example, to sort the response for the /account resource with the user accounts in organization 2 first, then all other user accounts, you would include the following option:

order.organization=/api/organization/2,*

Specifying a Query String in the Request Body

The API accepts a maximum URL size of 8 kb. If you need to perform a GET request with a query string that includes options and filters that would cause the URL to be larger than 8 kb, you can specify the query string in the body of the request. To do this:

Do not include the query string when specifying the URL in the request
Include the query string in the body of the request, excluding the leading question mark character
Include the content-type header "content-type:application/x-www-form-urlencoded" in the request

For example, the following cURL request specifies a GET request to the /ticket API that includes options and filters as part of the URL:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/ticket?limit=100&extended_fetch=1&filter.severity=3"

The following cURL performs the same request, but specifies the query string in the body of the request and includes the correct content-type header:

curl -v -H 'X-em7-beautify-response:1' -u 'em7admin:em7admin' "https://192.168.10.205/api/ticket" -H "content-type:application/x-www-form-urlencoded" -X GET -d 'limit=100&extended_fetch=1&filter.severity=3'

Required Options for Indexes

When you perform a GET request on some resource indexes, one or more options may be required. If a required option is missing, the response will contain a "302 Found" Status Code. The "Location:" header in the response will contain the URI for the resource with the option added. Typically the required option is a limit, which prevents responses from becoming too large.

Resource Responses

If you perform a GET request using the URI for a specific resource, the response has the following structure in JSON format:

{

"field":"value",

"custom_fields":{

"sub resource":{

"URI":"...",

"description":"...",

}

The XML response for the same request contains the same attributes in a similar structure.

The following sections are included in the response:

field:value pairs. In the structure shown above, field is the name of an attribute that is common to every resource of that type, e.g. "severity" for a ticket resource. value is the value of the attribute for this specific resource.
custom_fields. Has the same structure as the "field":"value" pairs, but for custom fields specific to this resource type in this SL1 systems.
sub resource links. In the structure shown above, sub resource is name of a sub resource associated with the resource type, e.g. "notes" for a ticket resource. Each sub resource in the response contains a URI for the sub-resource index and a description of the sub resource.

Creating and Updating Resources

To modify a resource, PUT or POST XML or JSON data to the resource URI.

The XML or JSON you include in a POST or PUT request must have the same format as an XML or JSON response from a GET request on the same resource. For example, if you:

Perform a GET request on a ticket resource and save the response in a file.
In the saved file, modify the value in a single field.
POST the XML or JSON back to the same ticket URI.

The modified field will be updated in the ticket.

When using POST to update a resource, the XML or JSON can contain only the fields that need to be updated; any fields you want to remain the same can be removed from the XML or JSON.

To create a new resource using a POST request, you must use the URI of the resource index. The new resource will be assigned a unique ID. The API returns the URI for the new resource in the response.

In the XML or JSON structure used in a POST request, the format of the data in each field must be identical to the format the API uses when responding to GET requests. For example:

Timestamps must be in UNIX timeticks format.
User passwords must be an MD5 hash of the actual password.

If you create a new resource using POST, the API ignores any links to sub-resources included in the XML or JSON structure. The response contains new URIs for sub-resource indexes.

For information on the difference between PUT and POST, see the HTTP Methods, Headers and Response Formats section.

If you use GraphQL for a bulk update, GraphQL will make multiple single calls to the REST API rather than one bulk call, even if SL1 does not use the bulk capability.

Asynchronous Operations

Asynchronous operations, such as starting a discovery session, can be performed using the POST method with the "application/em7-resource-uri" content type. The "application/em7-resource-uri" content type is proprietary to the ScienceLogic API.

The following actions are performed by POSTing an em7-resource-uri to another resource:

Starting a discovery session. POST a /discovery_session resource URI to the /discovery_session_active resource index.

Applying a device template. POST a /device_template resource URI to a specific /device or /devcie_group resource.
Performing a "Save As" operation on a dashboard. POST a /dashboard resource URI to the /dashboard resource index. All properties of the dashboard are copied, including those that cannot be modified directly through API requests.
Installing a PowerPack. POST a /filestore/powerpack resource URI to the /powerpack resource index.
Registering a Patch. POST a /filestore/system_patch resource URI to the /system_patch resource index.
Staging a Patch. POST a /system_patch resource URI to the /system_patch_stage resource index.
Installing a Patch. POST a /system_patch_stage resource URI to the /system_patch_deploy_active resource index.

For an example of how this content type is used, see the Example: Using the Discovery Resource section.

Links Between Resources

For fields in a resource that refer to another resource, the value for the field is the URI of the other resource. For example, if you request a ticket resource that is aligned to the System organization, the "organization" field contains the URI for the resource that represents the System organization:

"organization":"\/organization\/0",

This example shows the response from an SL1 PowerFlow in JSON format with the forward slash characters (/) escaped. If you are accessing the API through an Administration Portal, Database Server, or All-In-One Appliance, the "/api" portion of the base URI is included in all resource URIs returned by the API.

If you are creating, updating or replacing a resource that includes links to other resources, ensure that you include the URI for the other resource in the appropriate fields.

Size Limits

The API has the following limits for URI length and POST content:

The maximum URI length that can be used in an API request is 8199 characters.
The maximum size of JSON content that can be included in a POST request to the API is 2 GB.
The maximum size of XML content that can be included in a POST request to the API is 1,000,000 characters.