Introduction to the Jive REST API

Contents

1. Overview
2. Examples
3. Documentation Organization
4. Authentication
5. Important Features
   • Resources
   • Paginated Lists
   • Filters and Search
   • Mentions
   • API Item Limits
   • JSON Security String
   • Date Format
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:

• Content Service (/contents) for interacting with all content types, including Announcements, Discussions, Documents, Polls, and Posts (i.e. blog posts).
• Place Service (/places) for manipulating Blogs, Groups, Projects, and Spaces.
• Person Service (/people) for creating new users, deleting users, and updating users. To add Jive users to groups, use the /members endpoint.
• Activity Service (/activities) for retrieving and manipulating a user's activity stream. Related services include /actions for managing actions, /dms for handling direct messages, and /inbox for manipulating inbox entries.

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" ]
      }
   }
}

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

 {
    "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"
       }
    ]
 }

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, tag, search, 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>

<a href=\"https://example.jiveon.com/people/pauldoe\">Paul Doe</a>

<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

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

Date Format

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 + "'");
}

Versioning

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

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