Skip to main content

Get started with Moogsoft Cloud APIs

Before starting to use the Moogsoft Cloud APIs, it is helpful to understand some basic terminology, concepts, and fundamental procedures.

API: a definition

API stands for "application programming interface." An API includes a set of protocols that allow two applications to communicate with each other. Almost anytime you interact with a web application through your browser, you are interacting with an API somewhere.

In the specific case of Moogsoft, APIs can be used to perform tasks without going through the user interface. APIs can allow you to perform advanced tasks, scripted tasks, or non-standard tasks that the interface does not support.

Endpoints

An endpoint is a resource in an application that is able to interact with another software program in specific ways. It is capable of receiving a request and responding to it. An example of this in Moogsoft is sending a cURL request (covered below) to an endpoint to download collector software to set up on your computer.

Some other examples of Moogsoft endpoints include:

  • https://api.moogsoft.ai/v1/alerts-search

    Performs searches for alerts.

  • https://api.moogsoft.ai/v2/catalogs

    Returns a list of data enrichment catalogs.

  • https://api.moogsoft.ai/v1/incidents

    Lists incidents matching specified parameters.

Endpoints can receive information in a request to update data on the system, or respond by sending information to the requester.

Parameters

A parameter, in API terms, is a piece of information passed to an API endpoint to somehow modify the endpoint response. This information could be optional, or it could be required. When requesting a collector installation by API, for example, the request must include a string parameter which indicates the OS version (platform) of the collector setup to send. Other examples of parameters for different endpoints include filters, user IDs, alert IDs, and integration names.

REST

REST is an acronym for REpresentational State Transfer. A REST, or RESTful, API is an application programming interface that conforms to the REST architectural constraints rather than a protocol standard. The REST architecture is popular for developing stateless, reliable web APIs.

Client requests to RESTful APIs are typically delivered via HTTP in one of several formats: JSON (JavaScript Object Notation), HTML, XLT, Python, PHP, or plain text, with JSON being the most popular.

The OpenAPI Specification

In general terms, the OpenAPI Specification defines a standard format for the structure and syntax of REST APIs.

Per the OpenAPI Initiative:

"The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service."

Swagger

Swagger was originally a way of representing an API using JSON, built upon a REST API architecture, which provided a way to try out APIs and develop against them. Swagger later was renamed as OpenAPI Specification (OAS).

Swagger is now a set of open source development tools for producing REST-based APIs that adhere to the OpenAPI Specification. These tools includes applications for designing APIs (Swagger Editor), building APIs (Swagger Codegen), and documentation (Swagger UI).

For more details, visit swagger.io.

YAML files

YAML is a programming language used for creating configuration files. It either stands for "Yet Another Markup Language" or "YAML Ain't a Markup Language," depending on your preference. YAML is popular for use in Ansible, and for Kubernetes resources and deployments.

For the purposes of Moogsoft APIs, YAML files are produced as a part of the software development process and are used for documentation purposes. The Moogsoft API documentation is built from auto-generated YAML files.

Using Moogsoft APIs

After you grasp the basics, you can move on to experimenting with the Moogsoft APIs. The Moogsoft APIs are located at Moogsoft API Docs.

Using cURL requests

The term cURL stands for "client URL" and it is a way to deliver data to and from a server. It supports HTTP and HTTPS, though you will always use HTTPS with Moogsoft cURL commands to APIs.

Sending cURL requests to an API requires no additional setup for systems like MacOS and Linux, which have built-in shells. If you have a Microsoft-based system, you can install or enable a bash shell, depending on your OS version. Refer to the documentation from Microsoft, or search for third-party shell programs you can install on Microsoft platforms.

Testing API requests

To check if cURL requests are working on your system, you can send a test event that will create an alert in Moogsoft.

  1. Navigate to Integrations > Ingestion Services.

  2. Click Events API and copy the cURL command shown in the cURL Request box.

    You can click the clipboard icon to quickly copy the entire command.

  3. Paste the command into the command line interface of your shell program.

    For Linux and MacOS users, this involves simply pasting at the command line. Windows users may need to run a program to start up a shell program first.

    curlcommand.png

  4. Press Enter.

    A success message displays.

  5. To confirm that the event in the command successfully made it to your system, navigate to Incidents > Alerts and make sure you see the test alert.

‌

Note

You can also send commands to API service endpoints using Postman. For Postman installation instructions and educational materials, visit https://web.postman.co.

Building commands using the API documentation

After you have tested API functionality on your system, you are ready to move on to using the APIs to perform meaningful tasks. The Moogsoft API documentation includes the ability to interactively build API requests which can save time when customizing requests.

Use the following instructions to build a simple request to send to the Alerts service. It retrieves information about an alert in Moogsoft. You can use the alert you created in the test procedure if you need to do so.

  1. In your Moogsoft instance, navigate to Incidents > Alerts.

  2. Find an alert in the page and make a note of the value for the id column. You will supply this value as a parameter for the API endpoint.

  3. In your browser, access the the Company: Express Short API page.

  4. Find the Alerts/Incidents API on the left hand pane, and under the alerts section, navigate to the GET request called Get details of the alert with the specified ID.

  5. In the Auth and Parameters box on the right hand side, locate the alertId box.

  6. Type your id value from Step 2 in the box.

    Notice that when you enter information in the body of the page, the cURL request below also updates with the information.

    alertidboxhighlights.png

    For this request type, alertId is the only required parameter.

  7. Go back to Moogsoft and generate a new API key to use, and copy it.

  8. Back on the API docs page, paste your API key in the Auth and Parameters box next to apiKey.

  9. Click Send API Request to send the request.

    The Response displays under the Response section.

    results.png

Note that you can also copy the code from the Response Example section and modify it as needed, then send to an endpoint using a shell or Postman. To use a different language, select a new language from the Request Sample menu. The Request box updates with the same command in your selected language.

In this section: