Introduction to the REST API

Contents

  1. Overview
  2. Documentation Organization
  3. Authentication
  4. Important Features

Overview

The Yookos API provides comprehensive and powerful functionality for interacting with the Yookos community.

All REST endpoints use JSON in the request and response bodies. The JSON format for different 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 AnnouncementsDiscussions, Documents, Polls, and Posts (i.e. blog posts).

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

The /people endpoint is used for creating new users, deleting users, and updating users.  To add 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 API documentation is divided into 2 sections:

  1. Types
  2. Services
The Types section documents the JSON format for 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

Yookos v3 API makes use of OAuth tokens to authenticate developer keys. As such, a developer looking to invoke any service must register for a key at the API store It's important to only invoke the https services as user credentials are included in the URL when invoking any service.

Generate User Tokens

There are two ways to generate a user token.
  • Using the API Store
  • Using the API login API

Generate token through the Manager Store

Instructions to generate a user token and invoke APIs through the management console can be found in section Subscribing to an API.

Using the login API to generate User Tokens.

When a developer wants to invoke an API in the API Store through a third-party application like a mobile app, they can do so by first calling the login API to generate a token. It provides the base64 encoded string of the comsumer-key:consumer-secret combination.

Prerequisites
Before using the Login API to generate a user token, ensure the following requirements are satisfied.
  • A valid user account in the API Store. One can Signup at the API store.
  • A valid consumer key and consumer secret. Initially, these keys must be generated through the API store. Refer to Subscribing to an API for instructions. It shows how to generate the necessary keys by clicking the 'Generate' link on 'My Subscriptions' page.

With the requirements above satisfied, the steps below outline how to generate the user token.

  1. Combine the consumer key and consumer secret keys in the format 'consumer-key:consumer-secret' and encode the combined string using base64. For testing purposes, encoding to base64 can be done using the the site at: http://base64encode.org. An example consumer key and secret combination is: wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue.
  2. Access the Login API (You can test with a REST client or Curl), with the following parameters.
    • The Login API url is https://api.yookos.com:8243/login.
    • payload - "grant_type=password&username=<username>&password=<password>&scope=PRODUCTION". Replace the <username> and <password> values as appropriate.
    • headers - Authorization :Basic <base64 encoded string>, Content-Type: application/json. Replace the <base64 encoded string> as appropriate.

Renew User Tokens

After an access token is generated, users sometimes may have to refresh or renew the old token due to expiration or security concerns. This can be done by issuing a REST call to the Login API through (one can test via REST client or Curl, with the following parameters.

  • The Login API url is https://api.yookos.com:8243/login.
  • payload - "grant_type=refresh_token&refresh_token=<retoken>&scope=PRODUCTION". Replace the <retoken> value with the refresh token generated in the previous section.
  • headers - Authorization :Basic <base64 encoded string>, Content-Type: application/json. Replace the <base64 encoded string> as appropriate.

Important Features

Resources

Throughout the Yookos 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. 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 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 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 Yookos uses UTC time to avoid ambiguity. In this case the offset is +0000 for GMT. The Java SimpleDateFormat format string for parsing 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
    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 J-Script 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)