Introduction to the Jive REST API

Contents

  1. Overview
  2. Examples
  3. Documentation Organization
  4. Authentication
  5. Important Features
  6. 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 endpoints are described in the Services section. The most important REST endpoints include:

All endpoints use the prefix /api/core/v3. For example, if your Jive community is located at https://example.jiveon.com, you could query for all content in that community (using the /contents endpoint) by performing a GET request to the following URL: https://example.jiveon.com/api/core/v3/contents.

Examples

For a collection of introductory REST API examples, refer to REST API Examples on the Jive Developer Website.

Documentation Organization

The REST API documentation is divided into 2 sections:

  1. Types: documents the JSON format for Jive objects (also known as "entities") that are used to interact with the REST endpoints. In addition to a list of fields and resources associated with this entity, these pages often contain examples that illustrate how an entity is used. Refer to the Discussion Entity as a sample entity.
  2. Services: documents each REST endpoint. The pages are grouped by their top-level endpoints. For example, the Person Service (/people) includes how to create new users via POST requests to the /people URI, as well as how to remove users via DELETE requests to the /people/{personID} URI. Be sure to check the related Jive object Type for additional examples. In the case of Person-related endpoints, you should also look at the Person Entity for endpoint examples that use this Jive object.

Authentication

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

OAuth 2.0 is the preferred method for authentication. API access using OAuth 2.0 is supported through the Jive Add-on Framework.

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":"https://example.jiveon.com/api/core/v3/contents/1005/likes",
         "allowed":[ "GET" ]
      },
      "read":{
         "ref":"https://example.jiveon.com/api/core/v3/contents/1005/read",
         "allowed":[ "DELETE", "POST" ]
      },
      "self":{
         "ref":"https://example.jiveon.com/api/core/v3/contents/1005",
         "allowed":[ "DELETE", "GET", "PUT" ]
      },
      "html":{
         "ref":"https://example.jiveon.com/thread/1001",
         "allowed":[ "GET" ]
      },
      "attachments":{
         "ref":"https://example.jiveon.com/api/core/v3/attachments/contents/1005",
         "allowed":[ "GET", "POST" ]
      },
      "followingIn":{
         "ref":"https://example.jiveon.com/api/core/v3/contents/1005/followingIn",
         "allowed":[ "GET" ]
      },
      "messages":{
         "ref":"https://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:

PropertiesTypeDescription
startIndexintegerThe current page's offset into the list of all results
itemsPerPageintegerThe max number of items returned per page. Usually set with the count   query parameter. Most paginated results default to 25 itemsPerPage and can be set as high as 100 with the count parameter.
linksJSON ObjectObject containing URLs for getting the next or previous page of results. Has fields next  and prev (when available).
listJSON ArrayArray containing the retrieved Jive objects for the current page

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://example.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://example.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://example.jiveon.com/api/core/v3/announcements/1065",
                "allowed":[ "DELETE", "GET", "PUT" ]
             },
             "html":{
                "ref":"https://example.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://example.jiveon.com/api/core/v3/announcements?fields=publishDate%2Ccontent%2Csubject&count=1&startIndex=1

Filters and Search

Throughout the API, requests provide filters and search functionality for improving the results.

Many endpoints support filtering. For example, the REST endpoint GET /contents supports  filters for author, place, relationship, tagsearch, and others. In order to limit the search based on an author, you might perform this request:

GET https://example.jiveon.com/api/core/v3/contents?filter=author(https://example.jiveon.com/api/core/v3/people/15)

Using the search filter, you can perform 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 wildcards. 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".

GET https://example.jiveon.com/api/core/v3/contents?filter=search(Bob*Jones)

You can stack up multiple filters to further refine your results:

GET https://example.jiveon.com/api/core/v3/contents?filter=tag(rest,api)&filter=type(document,discussion)

Additionally, you can filter the results using the count and startIndex query parameters for pagination, as mentioned above.

Mentions

In Jive it is possible to mention a person, a place or a content. When mentioning a person, the mentioned user will receive a notification in their inbox. Mentioning a place will create a new entry in the activity stream of the place. All type of mentions will be rendered in the UI with a link that will take you to the mentioned object. To create a mention, you will need to include specific hyperlinks in the content.text element.

To mention a place, just add a hyperlink to the activity page of the place. For instance:

<a href=\"https://example.jiveon.com/community/water-cooler/activity\">Water Cooler</a>
To mention a person, add a hyperlink like this:
<a href=\"https://example.jiveon.com/people/pauldoe\">Paul Doe</a>
Finally, to mention a content you will need to add a hyperlink like this:
<a href=\"https://example.jiveon.com/docs/DOC-1365\">Title of the document</a>

Here we can see the complete JSON of a document that includes a mention.

{
    "content": {
        "text": "<body><p>Check out the <a href=\"https://example.jiveon.com/community/water-cooler/activity\">cooler</a>.</p></body>",
        "editable": false,
        "type": "text/html"
    },
    "subject": "Document with a mention",
    "authorship": "author",
    "categories": [],
    "visibility": "all",
    "restrictComments": false,
    "type": "document"
}

API Item Limits

When calling an endpoint that accepts a list of items, limit the number of items specified per call to 200. In the event that you want to specify more than 200 items, simply call the endpoint multiple times. For example, let's say you need to add 2,000 users to a security group. You can do this by calling the Create Members endpoint:

POST https://example.jiveon.com/api/core/v3/securityGroups/securityGroupID/members

You would want to call this method 10 times, each time with a separate set of 200 users, until you have added all users.

In REST API versions 3.11 and later, this limit is enforced at the API layer.

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)

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.

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://example.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.