Introduction to the ScienceLogic API

Download this manual as a PDF file

This section describes the functionality of the ScienceLogic API and is intended for developers who are responsible for integrating SL1 with external systems. To use this manual, you should have a general understanding of the HTTP protocol.

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 ().

What is the ScienceLogic API?

The ScienceLogic API allows external systems to programmatically access data in SL1. The API gives access to entities in SL1— such as tickets, devices, and collected data — using standard HTTP request/response protocols. Much like the user interface provides access to SL1 for end users, the API provides access to SL1 for external systems.

The following SL1 appliances provide access to the API:

  • All-In-One Appliances
  • Administration Portals
  • Database Servers

Accessing the API

This section gives a brief overview of how to communicate with an appliance that provides access to the API. All communication with the API is handled by HTTPS requests.

A request must include:

  • Valid SL1 login credentials. The API uses HTTP authentication methods. The credentials you include in the HTTP request are validated against the user accounts stored in the system.
  • A Resource URI. The URI for the resource (entity) you are performing the request on.

  • An HTTP Method. Correlates to the action you would like to perform on the resource.
  • An Accept Header. Specifies which format should be used for the response. The API supports application/xml and application/json formats.
  • The base URI of the API. The base URI of the API is the full address of the main API index. The base URI includes information about the appliance you are using to access 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

    • For SL1 PowerFlow, the base URI of the API is:

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

The response from the API contains:

  • An HTTP Status Code. Indicates the result of the request.
  • SL1-Specific Status Headers. Contains additional information about the result of a request. This information supplements the HTTP Status Code.
  • XML or JSON data. Information about the requested resource in the format specified in the request.

To familiarize yourself with performing basic requests, you can use a standard web browser:

  • Open a web browser.

    • When you request a resource from the API using a web browser, the API will respond in raw XML format. Some browsers, including Safari and Internet Explorer, will not display raw XML correctly. If possible, you should use Mozilla Firefox to perform these steps.

  • Navigate to the base URI of the API for the appliance you are using. The standard authentication window is displayed.
  • Enter the username and password for a user account in the system. The response for the main resource index is displayed.

The response contains a list of URIs for the resources that are available through the API:

Each entry in the list includes:

  • The URI of the resource.
  • A description of the resource.

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.

For example, the URI "/organization" has the description "Get/Update/Add/Delete Organizations". To view information about organizations, append the base URI of the API with the URI for the organization resource:

<base URI>/organization

The index for the organization resource, which contains descriptions and URIs for every organization in the system, is returned.

The browser handles the required elements of the request in the following ways:

  • The credentials you enter are used to authenticate the request. Most browsers will save these credentials so you need to enter them only once per session.
  • You enter the resource URI (/organization) in the browser address bar.
  • By default, the browser performs a GET request.
  • The browser supplies a default accept header with the request. The default accept header used by Mozilla Firefox contains "application/xml", one of the two response formats returned by the API.

Although using a web browser is the easiest way to make simple requests, using a browser provides limited control and functionality. For example, you cannot explicitly perform PUT, POST of DELETE requests with a browser. A browser will also handle certain aspects of requests and responses, such as automatically following redirects, differently than they will be handled by integration code. ScienceLogic recommends you use command line cURL to test requests. For examples on how to use command line cURL, see the Ticket Resource Example.

API Settings

The REST API Settings page System > Settings > API allows you to define global parameters that affect the behavior of the ScienceLogic API.

The REST API Settings page is available only to administrator users.

To define or edit the settings in the REST API Settings page:

  1. Go to the REST API Settings page System > Settings > API.
  2. In the REST API Settings page, edit the values in one or more of the following fields:
    • Internal Request Account. Specify the user account that allows appliances to make API requests without a password.
    • X-EM7-run-as Header Support. Specifies whether administrator users can make API requests using the permissions of another user without that user's password. Choices are
      • Disabled. Administrator users cannot make API requests using the permissions of another user.
      • Enabled (Admin only). Administrator users can include the X-EM7-run-as Header to make API requests using the permissions of another user.

    • Logging. Specifies which logs SL1 will write to when tickets are created or updated using the API. Choices are:
      • Transaction Logging Only (System Logs). If a ticket is created or updated using the API, SL1 will write an entry to the audit log that indicates that a user performed a write-operation using the API. However, SL1 will not write to the ticket log for the ticket that was created or updated.
      • Normal (Ticket and System Logs). If a ticket is created or updated using the API, SL1 will write to the audit log and to the ticket log for the ticket that was created or updated.

    • X-EM7-suppress-logging Header Support. If Normal (Ticket and System Logs) is selected in the Logging field, this field specifies whether an administrator can use the X-EM7-suppress-logging header can be used when creating or updating a ticket with the API. If the X-EM7-suppress-logging header is used when creating or updating a ticket, SL1 will not write to the ticket log for that ticket.
      • Disabled. The X-EM7-suppress-logging header cannot be used.
      • Enabled (Admin only). The X-EM7-suppress-logging header can be used to stop SL1 from writing to the ticket log for the ticket that was created or updated.
    • Send Notification. When a ticket is created or updated, SL1 can automatically send notification Emails to the ticket assignee and ticket watchers. This option specifies the conditions under which SL1 will send notification Emails when tickets are created or updated using the API. Choices are:
      • Only if X-EM7-send-notification:1 is sent. EM7 will send notification Emails for a ticket only when the X-EM7-send-notification header is set to 1.
      • Sent after every write operation. SL1 will send notification Emails for every API request that creates or updates a ticket.

  3. Select the Save button to save changes in this page.