RESTful API Quick Start Guide

About

The RESTful API is an important part of the integration layer for SevOne products.

Representational State Transfer (REST) is by definition an architectural style. There are clear principles for the implementation of RESTful API backend. The most notable one is statelessness. This refers to not relying on a temporary state (not part of the persistent model) to assure the calls are cached and forwarded to less busy appliances. However, the rules about RESTful API design from the user's perspective are not as strict or widely accepted.

There are multiple approaches as well as many guidelines and best practices for designing the RESTful API. These are imperative in order to deliver a stable and intuitive RESTful API across multiple teams and departments. Established standards and uniform design ensure better alignment between development teams, professional services, support, and customers.

SevOne's RESTful API implements the Swagger specification for API documentation. You can view SevOne API Documentation and perform operations related to SevOne NMS data using the Swagger User Interface. This document covers the use of Swagger User Interface with SevOne API.

• Alerts

• DeviceGroupRulesAlerts

• DeviceGroups

• Devices

• DeviceTypes

• Discovery (queue management)

• Indicators

• Maintenance Windows

• Metadata

• Metadata Attribute

• Metadata Namespace

• NetFlow

• ObjectGroup

• ObjectGroupRules

• Objects

• Peers

• Plugins

• Policies, Policy Conditions

• Report Attachments

  • Alerts

  • Device Groups

  • Devices

  • FlowFalcon

  • Group Metrics

  • Metadata

  • Object Groups

  • Objects

  • Performance Metrics

  • StatusMap

  • TopN

  • Topology

• Reports

• Tags

• Thresholds

• TopNViews

• Topology

• User Permissions

• User RolesDeviceTypes

• Users

• WorkHours

Prerequisites

A valid account in SevOne NMS is required.

Endpoints

An endpoint is a URL specifier for a single instance or a collection of instances of the same type. The type of instance, possibly id, must be simple and clear. Anything that you can name as an abstract entity in the context of your domain can be a resource. The endpoint is defined by a common understanding of the domain between the provider and consumer of RESTful API. Examples of types of instances include users, devices, reports, alerts, etc.

When creating an endpoint, use nouns (not verbs or other parts of speech). Always use plural form of the nouns. Even when you want to specify only one entity, use plural form and then id.

There are various ways to handle composite names such as devicegroup. For example, device_group or device-group can also be used. In this case, merge of words together is used i.e., devicegroup. This is how RESTful API was initially started; SevOne has used the same approach to make the interface more intuitive for the consumers.

When you want to specify an entity in relation to another construct, the endpoint must start with the bigger entity and end with the smaller one. The idea is to go from the whole to the parts or from the generic to the specific. As a general rule, the last part of the URL is the entity that is manipulated.

Methods

The endpoints are used in the URL to identify resource or collection of resources that you want to perform operations on. The operations are fairly limited to simple CRUD. All that can be done on the resources is defined by the HTTP methods.

Configuration

Versioning

Specifying the RESTful API version is mandatory. It refers to the major version of RESTful API you want to use. Add the version (v1 or v2) at the beginning of the URL.

Only specify the major version of RESTful API. Remember that for minor versions or small-fixes, there should be no comparability difference between the endpoints.

HTTP Headers

HTTP offers a wide range of headers to be used according to their HTTP-specified purpose.

The HTTP headers are used for metadata about the request itself and to clarify the communication between the consumer and the provider. They are not used to provide information about the content of this communication. Typical usage is authorization of tokens or active roles or format of the request or repose.

Content-Type: application/json
Accept: application/json

All dates that are sent or received by RESTful API are expressed in UNIX timestamps in milliseconds (Epoch Time multiplied by 1000). For example, 1634156442000 is Wednesday, October 13, 2021 16:20:42 PM GMT-04:00.

For all RESTful API calls with a date, it accepts timestamps and sends back timestamps regardless of whether it is a query parameter or DTP (Data Transfer Protocol) property or a HTTP method or request / response. There are no exceptions to this part of the convention.

Data Transfer Objects (DTOs)

DTOs are used to transfer structured data between the provider and the consumer of RESTful API. Currently, API supports the JSON format only.

In RESTful API, it is standard to have one DTO per type of resource (identified by a URL). However, this widely used pattern is not a 100% firm rule.

RESTful API services are composable which means, it allows services to be used in various combinations be achieve full workflows and scenarios. DTOs must be generic and allow for composing and re-usability. Please ensure you have re-usable DTOs.

Paging

When there are too many resources in a collection, it is standard practice to perform the request in batches. The result set is limited, and the RESTful API consumer can request the next batch. This does not require any session information or state of the request itself to be persisted. There are various recommended ways to implement this. Paging has been chosen as a standard in SevOne API.

Filtering & Sorting

    
http://...?sortBy=property1,-property2,property3...    

Swagger User Interface (UI) Examples

Endpoints with Sample Payload

Troubleshooting

After you execute an operation, you will see an HTTP status code in the Response Code section. This code represents the status of the operation. For example, 200 indicates that the operation was successful. If an operation fails, you may see information about the problem in the Response Body field. The following screenshot shows an error that occurs if you try to perform an operation without first authenticating. The relevant HTTP status code is 401, and the description for the code is Unauthorized. In this case, additional information about the error appears after "detail":.

The following table contains some common HTTP status codes along with their descriptions. For additional details on HTTP status codes, please refer to Hypertext Transfer Protocol (HTTP) Status Code Registry (https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

Return Codes

The table below lists the HTTP error codes returned when specific conditions are met during the execution of RESTful API requests.

RESTful API Logs

1. Using a web browser of your choice, log in to RESTful API swagger user interface.

   http://<PAS hostname or IP address>/api/docs/

   Please refer to section Authentication to obtain permissions to perform the operations.

2. To change logging level per logger, under Application, click POST /api/v2/application/logger.

3. Under Parameters, all the way to the right, locate the Model Schema field. Click on the field to copy its content to the logger field.

4. On the left side of the Parameters section, you will notice that the content now appears in the logger field.
   

   1. After "level":, replace string with a logging level from the list below. Please make sure to enter the logging level within the quotes.

      The log levels available are the following.

      Log Level	Description
      OFF	The OFF has the highest possible rank and is intended to turn off logging.
      FATAL	The FATAL level designates very severe error events that will presumably lead the application to abort.
      ERROR	The ERROR level designates error events that might still allow the application to continue running.
      WARN	The WARN level designates potentially harmful situations.
      INFO	The INFO level designates information messages that highlight the progress of the application at coarse-grained level.
      DEBUG	The DEBUG level designates fine-grained informational events that are most useful to debug an application.
      TRACE	The TRACE level designates finer-grained informational events than the DEBUG level.
      ALL	The ALL has the lowest possible rank and is intended to turn on all logging.

      
      

      By default, the log level is ERROR.

   2. After "logger":, replace string with the logger you want to get the log messages for. Please make sure to enter the value within the quotes.

      Logger	Description
      DATABASE	Enable logs for data persistence layer.
      INDICATOR_DATA	Enable logs for the indicator endpoints
      LDAP	Enable logs for the LDAP module.
      LIVEMAPS	Enable logs for livemaps.
      MESSAGESWITCH	Enable logs for messageswitch.
      org.hibernate.SQL org.hibernate.type root	Enable logs for SQL queries.
      REST	Enable logs for the requestd module.

      Multiple combinations of (level, logger) can be specified. In order to specify <n> combinations, <n> RESTful API calls must be made. For example, you can make RESTful API call for (DEBUG, REST) and another call for (WARN, DATABASE).

      Although default value for log level is ERROR, default string for the logger does not exist. If two RESTful API calls for (DEBUG, REST) and (WARN, DATABASE) are made, two more RESTful API calls (ERROR, REST) and (ERROR, DATABASE) are required to revert them.

      'logger' field examples

      {

        "level": "DEBUG",

        "logger": "REST"

      }

      Example: Enable SQL queries to the database

      {

        "level": "DEBUG",

        "logger": "org.hibernate.SQL"

      }

       

      {

        "level": "DEBUG",

        "logger": "org.hibernate.type"

      }

      Example: Enable logging for all modules

      {

        "level": "DEBUG",

        "logger": "root"

      }

5. At the bottom of the POST section, click the Try it out! button.

6. Please refer to Troubleshooting for the description of the Response Code returned after executing the RESTful API operation.

7. Using ssh, log into SevOne NMS appliance as root.

   $ ssh root@<SevOne NMS appliance IP address or hostname>

8. Logs can be found in /var/log/rest-api/SevOne-rest-api.log.

   When debugging, RESTful API's response time may be impacted because logs are being written to the log file.

   RESTful API debug settings are not persistent when SevOne-restapi is restarted.

   $ supervisorctl restart SevOne-restapi