Graze API

The Graze API is a REST-based API that acts as an integration point for external services and exposes selected Moogsoft Onprem functionality to authorized external clients.

Graze is a set of HTTP based web service endpoints within Moogsoft Onprem that allow external entities to

Interact with many Moogsoft Onprem objects remotely via HTTPS
Add, edit, remove, or retrieve most objects and configurations in Moogsoft Onprem
- Alerts and Situations
- Services and processes (Service Catalog)
- Probable root cause data
- Maintenance windows
- Users, roles, teams, authentication realms
- UI integration, algorithm, and workflow engine configuration data

Use caution when employing the Graze API. Excessive requests can impact overall system performance, especially getSituationIds and getAlertIds.

Contact Moogsoft Support if you experience difficulties or need further guidance.

Endpoints

See Graze API EndPoint Reference for details of all the Graze API endpoints.

URL encoding

You must URL encode the data in your cURL messages. You can encode the data yourself or you can send it "as is" and use the --data-urlencode option.

Before you begin

Moogsoft Onprem implements the Graze API as a set of servlets running in the Moogsoft Onprem Apache Tomcat instance. This instance handles external Graze requests, making the UI servlet calls directly via cross-contexts.

Configure Apache Tomcat

You must configure Apache Tomcat to allow cross-context calls to be made by adding the following to the context.xml file in the Apache Tomcat $APPSERVER_HOME/conf directory:

<Context crossContext="true">

API definition

All Graze requests use the following URL format, where <server> is the hostname of the machine running the UI :

https://<server>/graze/v1/<request_type>

For example:

https://localhost/graze/v1/authenticate

Authentication

All Graze API requests, other than authenticate, require a basic authentication header or a valid auth_token. You must make a valid authenticate request before using any Graze API request without a basic authentication header.

If you make regular Graze requests within a one hour timeframe, you are considered active and your session does not expire. Inactive sessions are logged out after one hour, and you must make a new authenticate request to get a new valid auth_token.

Authentication troubleshooting

If an error occurs during Graze login authentication, Moogsoft Onprem returns the following output:

{"message":"User is not authenticated","statusCode":3001}

As a security precaution, no more specific information is returned. This prevents information being provided to potential attackers about which part of the authentication failed (for example 'Password incorrect').

Entries in the log file catalina.out, at WARN level, provide more information on authentication errors:

For example, the user is not assigned the Grazer role:
```
User [john] does not have graze permission
```

For example, no user of that name exists:

User [NotAUser] account unknown in database

For example, incorrect password:
```
Password incorrect for user [graze]
```

POST parameters

You can send POST parameters as form-urlencoded or as application/json parameters.

form-urlencoded

To send POST parameters as form-urlencoded parameters, set the content type to application/x-www-form-urlencoded. If the character set is not set, UTF-8 is assumed.

Example cURL command:

"https://localhost/graze/v1/resolveSituation?auth_token=b40244fd79aa46fba76c60c56d538c49&sitn_id=10" --insecure -X POST -v

application/json

To supply POST parameters as JSON within the body of the request, set the content type to application/json. If the character set is not set, UTF-8 is assumed.