JobMon API

The JobMon API is, in most cases, not intended to be used directly by your code. It is used by the JobMon Dashboard which you can use to configure and monitor your jobs, the JobMon Agent which is installed on any server you wish to run JobMon jobs, the JobMon Scheduler which is used to identify when a job should be started and handles other necessary tasks for JobMon, and by the JobMon frameworks that you can reference in your code to make working with JobMon easier. If you do need to work directly with the JobMon API, this guide should help you understand it better.

The JobMon Entities:

• Job: An automated task
• Agent: A server that can run JobMon jobs
• Install: A job that is installed on an agent.
• Instance: A running job.
• Message: A logged message.

RESTful Services

The JobMon API follows common REST principles. It has a strong naming convention, so if you are looking for a list of all the jobs, you would call GET /api/jobs, agents would be GET /api/agents, etc. To determine which JobMon entities support what HTTP methods, check out the individual sections.

HTTP Verbs

In keeping with the HTTP nature of the JobMon RESTful interface, the JobMon API uses the following verbs: GET, POST, PUT, PATCH, and DELETE. Check with the individual entities (below) to see how each one uses the verbs, but here is some basics.

• GET: Used to fetch data. No data is changed as a result of this call. It can be used to query or fetch a single instance.
• POST: Used to add a new record. It is expected that the entire entity document is submitted. You must include required fields (see each individual entity for required fields).
• PUT: Similar to POST. The main difference is that it is used to update an existing document. Like POST, make sure you include the entire entity document.
• PATCH: Used to update individual fields in an existing document.
• DELETE: Used to remove an existing document.

HTTP Status

The JobMon API uses the HTTP status to indicate the success or failure of a particular API call.

• 200 OK: The API call succeeded. Check the body of the HTTP response for any expected data.
• 201 Created: The API call succeeded and a new document was created.
• 204 No Content: The API call succeeded. There is no content.
• 400 Bad Request: The API call failed. Check the body of the HTTP response for the specific error message.
• 404 Not Found: The requested document was not found.

Error Messages

When you receive a 400 Bad Request error, the HTTP body should contain a JSON object that explains the error.

{
  "message": "Something bad happened!",
  "name": "MyBadError",
  "code": "NativeCode"
}

The message and name fields should be included in every error message. However, the code field is only included if the original error included some kind of native code. This can be important for debugging the actual original cause of an error.

Queries

Each JobMon entity supports the ability to query it. Using the GET /api/xxx call, you can pass a MongoDB JSON query object in order to query the database. Pass this query using the q=... parameter (make sure you URL encode the JSON object).

Example: GET /api/instances?q=%7B%22started%22%3A%7B%22%24ne%22%3Anull%7D%2C%22completed%22%3A%7B%22%24eq%22%3Anull%7D%7D

Query select Parameter

You can also pass a select=... parameter in order to limit which fields are returned. This is a space-delimited list of fields that you would like to return. If you want to use a blacklist, just place a - in front of the field name and that field will be excluded.

Example: GET /api/instances?select=started%20completed

Query pageSize Parameter

Some queries might return an excessive number of records. In order to prevent major performance issues, JobMon limits the number of records that are returned to 50. If you want to change the default page size, you can send in a query string parameter of pageSize=##. The maximum value for this is 1000.

Example: GET /api/instances?pageSize=100

Query page Parameter

You can navigate pages by sending in the query string parameter page=##. This will just to whatever page you requested.

Example: GET /api/instances?page=3

The Query Response

The JSON response will include the data, plus a number of other fields that are useful in determining paging.

• data: Contains the data that you requested.
• page: The page number that this data represents.
• pageSize: The maximum number of records in the page. Check data.length for the actual number of records.
• total: The total number of records that were found in the query.
• links: Includes prev and next links in order to navigate the pages. You can check for the existence of the prev or next to determine if there are any other pages.

Example: GET /api/messages?pageSize=1 (uses test data, page size set to show paging)

{
  "data": [
    {
      "_id": "58004dfdb34879ac2cd4349f",
      "job": "58004dfdb34879ac2cd43490",
      "instance": "58004dfdb34879ac2cd4349d",
      "logLevel": "Info",
      "message": "This is a test info message",
      "__v": 0,
      "created": "2016-10-14T03:16:13.932Z"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 2,
  "links": {
    "prev": null,
    "next": "http://localhost:8000/api/messages?pageSize=1&page=2"
  }
}