HTTP Methods, Headers and Response Formats

Download this manual as a PDF file

The following sections cover how the API uses elements of the HTTP protocol to handle and respond to requests.

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 the menu options, click the Advanced menu icon ().

This section includes the following topics:

HTTP Methods

To perform operations on API resources, you can use one of the following four HTTP methods in your requests. Each resource has a different set of rules that determines which of the four methods can be used to make requests.

GET

GET fetches resources. The response to a GET request contains information about the resource you requested.

POST

POST updates an existing resource or creates a new resource:

  • To update a resource, use the POST method in a request to a specific instance of a resource. For example, to update a ticket with ID "1", you would POST JSON or XML data to the following URI:

    • /ticket/1

    If POST is used to update a resource, not all attributes of the resource need to be specified. The API will update only the attributes specified in the request.

  • To create a resource, use the POST method in a request to the index for that resource. For example, to create a ticket, you would POST JSON or XML data to the following URI:

    • /ticket

    The system creates a unique ID for the new resource. The URI for the new resource is based on the unique ID for the resource.

PUT

PUT adds or replaces a resource. Unlike POST, PUT will replace an entire resource. PUT requires a specific resource URI. The result of a PUT request will be consistent if the request is repeated.

DELETE

DELETE removes resources. If a resource allows the DELETE method, a successful DELETE request will remove the corresponding entry in the ScienceLogic Database.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the general result of a request. Every response from the API will have one of the following status codes in the header:

  • 200 OK. Indicates that the request was valid and the transaction executed normally.
  • 201 Created. Indicates that a new resource was created. 201 Created is not used when a resource is updated.
  • 202 Accepted. Indicates the request was accepted for processing.
  • 204 No Content Returned. Indicates the request was successful but the API returned no content. This response is typical when a file is uploaded via a PUT request.
  • 301 Moved Permanently. Indicates that the request was made on a sub-resource, but the sub-resource ID used in the request URI does not match a sub-resource associated with the main resource. For example, a GET request was made for an interface (the sub-resource) for a device (the main resource), but the interface ID in the URI is associated with a different device than the device ID used in the URI.
  • 302 Found. Indicates that the request did not include required options or filters. If a response has a 302 Found status code, a "Location" header will be included in the response. The "Location" header will contain the URI of your request with the default required options or filters included.
  • 303 See Other. Indicates that the request is not the preferred means of fetching the resource. If a response has a 303 See Other status code, a "Location" header will be included in the response. The "Location" header will contain the URI for the preferred means of fetching the resource.
  • 400 Bad Request. Indicates that the XML or JSON posted with the request contained bad syntax or was missing required fields.
  • 401 Unauthorized. Indicates invalid credentials were provided for authentication.
  • 403 Forbidden. Indicates that the credentials provided for authentication were valid, but the user is not permitted to access the resource.
  • 404 Not Found. Indicates that there is no resource at the URI specified in the request.
  • 405 Method Not Allowed. Indicates that the method used in the request is not permitted with the specified resource. For example, the DELETE method cannot be used on a ticket resource.
  • 406 Method Not Acceptable. Indicates that the accept header included in the request does not allow an XML or JSON response.
  • 415 Unsupported Media Type. Indicates that the content-type provided in a PUT or POST request is not supported.
  • 500 Internal Server Error. Indicates that a general error has occurred with the request that is not described by another status code. The X-EM7-Status-Message header may contain more information.
  • 501 Not Implemented. Indicates that the requested resource is a placeholder for future use.

SL1-Specific Headers

Response Headers

In addition to HTTP status codes, every response from the API includes headers that provide additional details about the result of a request:

  • X-EM7-Implemented-methods. A comma-delimited list of methods that are supported by the requested resource. This header is intended to provide information on the actions that can be performed on a given resource. For example, if you perform a GET request on the /device resource index, X-EM7-Implemented-methods will contain "GET,POST", the two methods supported by /device. If you perform a GET request on a specific device (e.g. /device/1), the X-EM7-Implemented-methods header will contain "GET,POST,PUT,DELETE", because a specific device resource supports all available methods.
  • X-EM7-Applicable-resources. A comma-delimited list of base URIs for resources that can be applied to the requested resource. For example, to start a discovery session through the API, you would POST a specific /discovery_session resource to the /discovery_session_active resource index; therefore, if you perform a GET request on the /discovery_session_active resource index, the response will include a X-EM7-Applicable-resources header of "/discovery_session". For more information on applying resource URIs to other resources, see the Asynchronous Operations section.
  • X-EM7-authenticated-user. The URI of the user account that authenticated the request. If the request included the X-EM7-run-as header, the X-EM7-authenticated-user will return the run-as user.
  • X-EM7-status-code. Typically a human-readable version of the HTTP Status Code. For certain errors, X-EM7-status-code might include additional information about why a request was unsuccessful. For example, if a response has the HTTP Status code "400 Bad Request", the X-EM7-status-code might be "FAILED_INPUT_VALIDATION".
  • X-EM7-status-message. A human-readable description of the result of a request. The X-EM7-status-message can contain multiple messages delimited by a newline character (\n). For example, if a response has the HTTP Status code "302 Found", the X-EM7-status-message might be "ticket index requires a limit", indicating the request was missing the required limit option.

  • X-EM7-Last-updated. This header is returned only when requesting device configuration data from the API. Returns the date and time that at least one value in the returned data changed.

Request Headers

The following ScienceLogic-specific headers can be used when making an API request:

  • X-em7-beautify-response. By default, responses from the API use the minimum required amount of whitespace. If you are making requests using a tool that does not format the output (such as command line cURL), specify the X-em7-beautify-response header with a value of "1" to request additional whitespace in the response to make it easier to read.

    • Using the X-em7-beautify-response:1 header can greatly increase the amount of time required to process a request. Do not use this header in integration code.

  • X-em7-run-as. The X-em7-run-as header can be used by administrator users to execute a request as a different user. For information about the X-em7-run-as header, see the section on Authentication and Access Permissions.
  • X-em7-suppress-logging. If the system is configured to write to an entry in the ticket log when a ticket is modified via the API, the X-em7-suppress-logging header can be used to modify a ticket via the API without updating the ticket log. If the X-em7-suppress-logging header with a value of "1" is included in an API request that modifies a ticket and the request is authenticated by an administrator user, the ticket logs will not be updated based on the result of the request.
  • X-em7-send-notification. When a ticket is created or updated, SL1 can automatically send notification Emails to the ticket assignee and ticket watchers. If the system is not configured to send notification Emails when tickets are created or updated using the API, the X-em7-send-notification header can be used to send notification Emails for a specific request. If the X-em7-send-notification header with a value of "1" is included in an API request that modifies a ticket, notification Emails will be sent based on the result of the request.

Response Formats

The API can respond in XML and JSON formats. Use one of the following accept headers in your requests:

  • accept: application/json, */*. The API will respond in JSON format. If the accept header is "*/*", the API will respond with JSON as the default response format; however, it is recommended that you explicitly accept "application/json" for clarity.
  • accept: application/xml, */*. The API will respond in XML format.

If the accept header for a request does not include application/xml, application/json or */*, the API will respond with a "406 Method Not Acceptable" status code.

The contents of responses are described in the Resources & URIs section.