Graze API

The Graze API acts as an integration point for external services and exposes selected Moogsoft Enterprise functionality to authorized external clients.

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.

Before you begin

Moogsoft Enterprise implements the Graze API as a set of servlets running in the Moogsoft Enterprise 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 Enterprise 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.

Example cURL command:

"https://localhost/graze/v1/resolveSituation" -H "Content-Type: application/json; charset=UTF-8" --insecure -X POST -v --data '{"auth_token" : "b40244fd79aa46fba76c60c56d538c49","sitn_id" : 10}'

To learn more, watch the Graze API Fundamentals training video at Moogsoft University