REST API

Obsidian includes a REST API to ease integration into other applications and software environments, regardless of the technology used. A complete range of job, scheduling and host management features are exposed via the API. It is exposed by both the standalone and bundled versions of the admin web application.

This page contains general information on the REST API, including data formats, authentication and common API behaviour.

For full details specific API endpoints, see Endpoints.

Note: Obsidian also has an Embedded API, which can be used when no web application is available or you'd simply rather not use REST.

Overview

The Obsidian REST API allows other applications a way to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways. It can be integrated with any programming language since it uses standards like HTTP and JSON.

The REST API gives users the power to do things like automate migration scripts, trigger jobs based on events in external applications, and expose pieces of the Obsidian API in their own custom user interfaces.

Endpoints

The API is exposed under the path /rest.

For example, if your web application is deployed at localhost, the jobs endpoint is accessible at http://localhost/rest/jobs.

For full details on the API endpoints, see Endpoints.

Data Format

JSON is used for all endpoints. This includes response data and PUT/POST data.

The returned Content-Type will always be application/json using the UTF-8 encoding.

All PUTs and POSTs must include Content-Type header set to application/json with a valid JSON body. UTF-8 should be used as the content encoding for maximum compatibility.

Authentication & Authorization

The REST API is secured by limiting access to users configured in User Management with the API Access role.

Valid basic access authentication must be supplied with every request. Valid API users are authorized to access any REST endpoint.

Disabling Authentication

In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

This can be done by changing the scheduler setting allowAnonymousRestCalls under the Dispatch category to true. When this is done, no Authentication header needs to be provided.

Note: This is not recommended on networks exposed to the Internet, or other non-trusted environments.

Common API Behaviour

• For GET and DELETE, parameterization is done via request parameters, and not JSON body. Supported parameters are simple and primarily provide search options and simple flags.
• All non-200 responses will always return a JSON response in the following format. One or more errors may be returned in the errors property.

{ 
    "errors":["nickname is required.", "jobClass is required."]
}

{ 
    "errors":["Resource not found"]
}

• If a request does not pass validation or if an action cannot be performed, a 400 status code will be returned. This may happen if required fields are omitted, in an invalid format, or an action cannot be performed in the current context.
• If a JSON payload contains unexpected fields, a 400 status code will be returned.
• If a resource with the specified identifier could not be found, a 404 status code will be returned. For example, this would occur if you attempt to load a job with an ID that does not exist.
• If an incorrect method is used on an endpoint (e.g. DELETE on a job runtime), a 405 status code will be returned.
• If no valid basic authentication is provided, a 401 status code will be returned.
• If no endpoint exists at the requested path, a 404 status code will be returned.
• If the Content-Type header of a PUT or POST request is not application/json, a 415 status code will be returned.
• If the server encounters an unexpected error, a 500 status code will be returned.

Date Formats

Since scheduling is inherently linked to time zones and is not fully represented by a UTC time, all times in the API are returned in the following string format. Note the trailing timezone indicator which indicates the UTC offset.

yyyy-MM-dd'T'HH:mm:ssZ

For example, the last second of 2012 PST is:

2012-12-31T23:59:59-0800

When a date only is input or output (as with custom calendars), it is always in the following format:

2012-12-31

Date & Time Inputs

While datetimes are always output in the same format, datetimes in query strings or in JSON payloads can use either the standard output format shown above, an abbreviated form that contains no timezone offset and assumes server time, or the UTC time represented as milliseconds since the epoch. For example, the last second of 2012 PST is:

2012-12-31T23:59:59-0800

Or, interpreted in the server time zone:

2012-12-31T23:59:59

Or, as milliseconds since the epoch:

1356987599000

Common Enumerations

Enumerations are consistent with the Embedded API's enumerations.

Note: Prior to 2.5, Enumerations in the REST API would in some cases return values with spaces instead of underscores, and would accept enumerations in requests in the same format. This is no longer supported.

JSON Bean Classes

As of version 2.3, Obsidian comes bundled with simple bean classes in the package com.carfey.ops.api.bean that can be used to serialize JSON requests and deserialize responses into plain old Java objects (POJOs). These bean classes are located in obsidian.jar which is included in your Obsidian zip download within the standalone directory.

These classes are tested with Gson since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.

Compatibility Note: If upgrading to Obsidian 2.5, you will notice that bean classes for requests now use typed enumeration values instead of String values. You may have to make small modifications to your code which uses these classes.

Each endpoint documents the appropriate bean class to use.

Serializing & Deserializing Date Types

Since the Obsidian REST API uses its own specific date formats to fully represent scheduled times including their time zones, you will have to use custom serializers to properly use the supplied bean classes. Doing this is simple, and we've provided a sample below for Gson, plus a generic example to show you how to parse and format dates appropriately, which you can adapt for use in JSON other libraries.

GSON Serialization:

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateTime;

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateFormat.ParseException;
import com.carfey.jdk.lang.DateTime;
import com.carfey.jdk.text.Json;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;


public class GsonDemo {
	public static void main(String[] args) throws ParseException {

        // Set up the custom serializers for date types
        GsonBuilder gb = new GsonBuilder();
        gb.registerTypeAdapter(Date.class, Json.REST_SERIALIZER);
        gb.registerTypeAdapter(DateTime.class, Json.REST_SERIALIZER);
        Gson gson = gb.create();

        // The Gson instance can now be used with all Obsidian REST bean classes
        SampleBean sample = new SampleBean();
        String stringValue = gson.toJson(sample);
        System.out.println(stringValue);

        SampleBean rebuilt = gson.fromJson(stringValue, SampleBean.class);
        System.out.println(rebuilt);
    }

    private static class SampleBean {
        private com.carfey.jdk.lang.Date date = new Date();
        private com.carfey.jdk.lang.DateTime dateTime = new DateTime();
        public Date getDate() {
            return date;
        }
        public void setDate(Date date) {
            this.date = date;
        }
        public DateTime getDateTime() {
            return dateTime;
        }
        public void setDateTime(DateTime dateTime) {
            this.dateTime = dateTime;
        }
        @Override
        public String toString() {
            return "SampleBean [date=" + date + ", dateTime=" + dateTime + "]";
        }

    }
}

Output:

{"date":"2013-10-30","dateTime":"2013-10-30T22:04:24-0700"}
SampleBean [date=20131030, dateTime=20131030 10:04:24:000 PM -0700]

Generic Date Parsing and Formatting Example:

// converting REST date time formats (serialize and deserialize)
com.carfey.jdk.lang.DateFormat dateTimeFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd'T'HH:mm:ssZ");

com.carfey.jdk.lang.DateTime dateTime = new com.carfey.jdk.lang.DateTime();
String dateTimeString = dateTimeFormat.format(dateTime);
com.carfey.jdk.lang.DateTime asDateTime = dateTimeFormat.parse(dateTimeString);
System.out.println(asDateTime);

com.carfey.jdk.lang.DateFormat dateFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd");

com.carfey.jdk.lang.Date date = new com.carfey.jdk.lang.Date();
String dateString = dateTimeFormat.format(date);
com.carfey.jdk.lang.Date asDate = dateTimeFormat.parse(dateString).getDate();
System.out.println(asDate);

Output:

20131105 06:10:41:000 PM -0800
20131105