Introduction to the REST API

Overview
Documentation Organization
Authentication
Important Features
Versioning

Overview

The Jive REST API provides comprehensive and powerful functionality for interacting with your Jive community.

All REST endpoints use JSON in the request and response bodies. The JSON format for different Jive objects is provided in the Types section. Fields marked as required must be specified when creating and updating objects. Optional fields can be specified on create and update, but the request will succeed whether or not they are provided. Fields marked as read-only are returned as data and will be ignored if included in a POST or PUT request. As an example, the Announcement page describes the JSON format for an announcement. It also gives the minimum JSON for creating a new announcement with a POST.

The most important REST endpoints include:

/contents
/places
/people
/activities

The /contents endpoint is for interacting with all content types, including Announcements, Discussions, Documents, Polls, and Posts (i.e. blog posts).

The /places endpoint allows for manipulating Blogs, Groups, Projects, and Spaces.

The /people endpoint is used for creating new users, deleting users, and updating users. To add Jive users to groups, use the /members endpoint.

Similarly, /activities is used for retreiving and manipulating a user's activity stream. Related endpoints include /actions, /dms for direct messages, and /inboxfor manipulating inbox entries.

Documentation Organization

The REST API documentation is divided into 2 sections:

Types
Services

The Types section documents the JSON format for Jive objects that are used to interact with the REST endpoints. The Services section documents each REST endpoint in detail. The pages are organized by the top-level endpoints. For example, the /people endpoint includes creating new users via POST requests to the /people URI, as well as DELETE requests to endpoints of the form /people/{personID}.

Authentication

Basic HTTP Auth is used for all authentication. The username and password should correspond to a user in a Jive community.

Important Features

Resources

Throughout the Jive API, returned JSON objects contain a field called "resources." Resources are key to successfully using the API. Resources contain an object's unique URI and URIs for related objects and HTTP actions.

For example, suppose you create a discussion. The returned JSON will include data about the discussion and a resources field. The URI of this discussion is in the self resource. There is a REST endpoint to get the "likes" of a discussion, so there is a likes resource for obtaining this data. You can mark a discussion as being read, so there is a corresponding resource for this also. The html resource is a URL suitable for viewing the object in a browser. In general, to perform actions on a Jive object and related objects, examine the resources of that object.

Note the allowed field gives the HTTP verbs that are allowed for a resource.

Example Discussion resources:

{
   "resources":{
      "likes":{
         "ref":"http://example.jiveon.com/api/core/v3/contents/1005/likes",
         "allowed":[
            "GET"
         ]
      },
      "read":{
         "ref":"http://example.jiveon.com/api/core/v3/contents/1005/read",
         "allowed":[
            "DELETE",
            "POST"
         ]
      },
      "self":{
         "ref":"http://example.jiveon.com/api/core/v3/contents/1005",
         "allowed":[
            "DELETE",
            "GET",
            "PUT"
         ]
      },
      "html":{
         "ref":"http://example.jiveon.com/thread/1001",
         "allowed":[
            "GET"
         ]
      },
      "attachments":{
         "ref":"http://example.jiveon.com/api/core/v3/attachments/contents/1005",
         "allowed":[
            "GET",
            "POST"
         ]
      },
      "followingIn":{
         "ref":"http://example.jiveon.com/api/core/v3/contents/1005/followingIn",
         "allowed":[
            "GET"
         ]
      },
      "messages":{
         "ref":"http://example.jiveon.com/api/core/v3/messages/contents/1005",
         "allowed":[
            "GET",
            "POST"
         ]
      }
   }
}

Paginated Lists

REST services for retrieving multiple entities return data as paginated lists in a consistent format throughout the API. Paginated lists have the following properties:

Properties	Type	Description
`list`	`JSON Array`	Array containing the retrieved Jive objects for the current page
`startIndex`	`integer`	The current page's offset into the list of all results
`itemsPerPage`	`integer`	The max number of items returned per page. Usually set with the `count` query parameter.
`links`	`JSON Object`	Object containing URLs for getting the next or previous page of results. Has fields `next` and `prev` (when available).

For example, to retrieve the list of system announcements with one per page, including only the fields publishDate, content, and subject, one could make the following request:

GET https://mycompany.jiveon.com/api/core/v3/announcements?count=1&fields=publishDate,content,subject

The returned JSON would look similar to the following:

 {
    "startIndex":0,
    "itemsPerPage":1,
    "links":{
       "next":"https://mycompany.jiveon.com/api/core/v3/announcements?fields=publishDate%2Ccontent%2Csubject&count=1&startIndex=1"
    },
    "list":[
       {
          "type":"announcement",
          "publishDate":"2012-08-23T15:16:49.167+0000",
          "content":{
             "type":"text/html",
             "text":"test announcement"
          },
          "subject":"some announcement's subject",
          "resources":{
             "self":{
                "ref":"https://mycompany.jiveon.com/api/core/v3/announcements/1065",
                "allowed":[
                   "DELETE",
                   "GET",
                   "PUT"
                ]
             },
             "html":{
                "ref":"https://mycompany.jiveon.com/",
                "allowed":[
                   "GET"
                ]
             }
          },
          "id":"1065"
       }
    ]
 }

One can then perform a GET request to obtain the next page of results (containing a single announcement) by using the links.next field. In this case the links.next URL simply incremented the startIndex parameter:

GET https://mycompany.jiveon.com/api/core/v3/announcements?fields=publishDate%2Ccontent%2Csubject&count=1&startIndex=1

Date Format

The Date format used is based on the ISO 8601 standard, but has additional restrictions. The time field and the timezone must be included. For example, September 1st 2012, 11 AM in GMT would be written as 2012-09-01T11:00:00.000+0000. Note that the UTC offset is required, because Jive uses UTC time to avoid ambiguity. In this case the offset is +0000 for GMT. The Java SimpleDateFormat format string for parsing Jive dates is "yyyy-MM-dd'T'HH:mm:ss.SSSZ". Here's a code example of parsing and obtaining the time in ISO 8601 format using Java.

public void parseDates() {
    // Strict ISO 8601 date format with UTC offset (Jive)
    SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");

    // Parse a date and print out the result in the ISO 8601 format
    String dateString = "2012-09-01T11:00:00.000-0700";
    Date date = dateFormat.parse(dateString);
    System.out.println("Parsed date: '" + dateFormat.format(date) + "'");

    // Get the current Date in ISO 8601
    String currentDateString = dateFormat.format(new Date());
    System.out.println("Current date in ISO 8601: '" + currentDateString + "'");
}

See the Javascript API for examples in javascript.

Filters and Searching

Throughout the API, requests to get paginated lists of objects provide filters and search functionality for improving the results. For example, the REST endpoint GET /contents allows for the filters author, count, fields, place, search, startIndex, tag, and type. The count and startIndex query parameters are the parameters mentioned above for pagination. Providing the search field performs a search based on text in the content of objects, typically searching the subject, description, and content or content.text fields (for types containing these fields). The search field supports wild cards. For example, if you want to search for "Bob Smith Jones" but you don't know that his middle name is "Smith", then you can search for "Bob*Jones".

JSON Security String

GET requests are protected by including a security string on the line before the JSON text. The string generally looks like "throw 'allowIllegalResourceCall is false.';". To strip out this string, a regular expression should be used. For example, in python one could use:

json = re.sub(r"^throw.*;\s*","",json)

Versioning

The Jive REST API is versioned separately from Jive product releases. Multiple API versions are supported in each Jive release in order to provide backwards compatibility. To query which API versions are available issue a request like the following:

GET https://mycompany.jiveon.com/api/version

The returned JSON will look similar to the following:

{
  "jiveVersion" : "6.0.0.0",
  "jiveCoreVersions" : [ {
    "version" : 2,
    "revision" : 3,
    "uri" : "/api/core/v2"
  }, {
    "version" : 3,
    "revision" : 1,
    "uri" : "/api/core/v3"
  } ]
}

In this example, API versions 2.3 and 3.1 are supported. Each API version number is in the form [MAJOR].[MINOR]. Major releases involve significant changes to the API, while minor involve only backwards-compatible changes (e.g. adding new service endpoints). In some cases, classes and methods will have a Since label in the documentation that identifies the API version that the feature was added in.

Introduction to the REST API

Contents