REST V3 API - Tips & Tricks

Version 8

    Overview

    This document is meant to be a complement to the existing documentation set.  Above everything else, we want this document to be a way for community developers to share their cool tricks with the API.

     

    The following materials should be used as a primer to using the REST v3 API

     

    Basics

     

    Authentication

    The Jive API has 2 models of authentication:  HTTP Basic and OAuth2.  There is a 3rd mechanism (HTTP Session), which allows users to introspect the API directly from the Web Browser when already logged into Jive; however, given it's limited applications for building actual solutions ... we will not focus on it further.

     

    HTTP Basic

    This is the easiest authorization mechanism; however, it requires that username/password be Base64 encoded and passed to Jive on every request.  As long as you are using HTTPS, this is fine; however, this pattern tends to fail in an enterprise setting.  This pattern is recommended for testing API end-points.

     

    Example Header:

    Authorization: Basic Y3VyaW9zaXR5a2lsbGVkdGhlY2F0PSk=

    See: Basic access authentication - Client side - Wikipedia for more details about HTTP Basic Authentication

    OAuth2

    This is the most enterprise grade way to interact with the Jive API. In addition to not sending sensitive information across the wire (like HTTP Basic), should a Bearer token be compromised, it can be managed/revoked by the user and re-issued.  See: for more details on this life-cycle OAuth 2.0—Creating a Client and Managing Access for more details on establishing an OAuth connection with the Jive API.

     

    Example Header:

    Authorization: Bearer YOUR_TOKEN_VALUE

    See: OAuth 2 Simplified • Aaron Parecki > Making Authenticated Requests for more clarity on OAuth2

     

    cURL

    cURL is a command-line utility available on most modern operating systems (may need to be installed) that allows users to synthesize HTTP(s) Requests to web services.

     

    Example Usage(s):

    curl -v -u "username:password" -k --header "Content-Type: application/json" "https://community.jivesoftware.com/api/core/v3/people/@me"

    curl -v -k --header "Content-Type: application/json" --header "Authorization: Bearer YOUR_TOKEN_VALUE" "https://community.jivesoftware.com/api/core/v3/people/@me"

    See also: REST API v3 Examples for some more curl + v3 examples for GET, PUT, POST and DELETE.

    See also: curl  for the official curl documentation

     

    Postman

    Postman is an exceptional tool accessible via the web browser that allows developers to access API.

    See: Postman | Supercharge your API workflow for more details.

    Note:  Be careful about session cookie bleed over with Postman.  In some cases, this can lead to erroneous results, especially when trying APIs that require OAuth2 tokens.

     

    Tips & Tricks

    If you'd like to add a Tip or Trick to this section, please just create another Heading 2 under this section and/or update an existing section.

    Suppressing Fields from API Responses

    The Jive can return quite a bit of information.  In some cases, this is overwhelming and ill-performant for your use-cases.  While there are a few fields that cannot be suppressed, most of them can.  Here are some quick examples that shows you how to tame the output.

     

    Example Usage(s):

    https://community.jivesoftware.com/api/core/v3/contents/1188411?fields=-resources  - Blanket kill all resources for the piece of content

    https://community.jivesoftware.com/api/core/v3/contents/1188411?fields=-resources,-author.resources - Kill all resources AND kill resources for a child attribute using JSON notation

    https://community.jivesoftware.com/api/core/v3/contents/1188411?fields=subject,author.displayName,resources.self,-author…  - Only a specific resource field and specific child attributes

    https://community.jivesoftware.com/api/core/v3/people/@me?fields=jive.profile,-resources - Just the profile fields of the logged in user (or who owns the token)

    https://community.jivesoftware.com/api/core/v3/people/@me?fields=jive.profile.Company,-resources - Just a single profile field (using value of "jive_label" to target)

    Note:  These examples work on the Contents , Places and Person service documentation.

     

    Quickly Get API ID for Jive Place/Content/User

    If you are looking to quickly get to the API ID, there is a quick trick to get to the API ID.  When you are viewing the object in the web browser, simply add the suffix /api/v3 to the URL and you should get the API representation of that Jive Object.

    Note:  Does NOT currently work with OAuth Tokens, only Basic/Session.  A ticket has been filed to address this jiveURL to Jive API ID in a more universal manner.

    Example Usage(s):

    https://community.jivesoftware.com/docs/DOC-233174/api/v3

    https://community.jivesoftware.com/community/developer/api/v3

    https://community.jivesoftware.com/people/ryanrutan/api/v3

    Note:  You can also combine this with the ?fields argument to restrict the output of this call.  See the corresponding Content , Place and Person service documentation for more details.

    Entity Descriptor Filter to Get API ID for Jive Place/Content/User

    The entity descriptor filter is historically the best way to universally convert from the native Jive objectType/objectID model to the API ID for a given place or piece of content.   This version works with all API authentication models.

    See: Contents & Places services > Filters > entityDescriptor for more documentation

     

    Example Usage:

    https://community.jivesoftware.com/api/core/v3/contents?filter=entityDescriptor(102,233174) - This Document

    https://community.jivesoftware.com/api/core/v3/places?filter=entityDescriptor(14,4340) - The Developer Space

     

    How to Obtain ObjectType and ObjectID Parameters

     

    For legacy Jive development (i.e. plugins), obtaining the objectType/objectID underneath the covers via the JiveObject class is quite simple; however, if you are trying to retrieve these values in an ad-hoc fashion from the UI ... it is a little less straight forward.  Here are some quick tips on grabbing these values that are relatively painless.

     

    • Places - In the Actions or Manage Menus, mouse-over the links and watch the status bar (or click through and look at the URL)
      • Common containerType values : 14 = Spaces, 37 = Blogs, 600 = Projects, 700 = Social Groups
    • Content - In the Actions Menu (or Sidebar), mouse over actions like Report Abuse and watch the status bar (or click through and look at the URL)
      • Common contentType values: 1 = Discussion, 2 = Message (in a Discussion), 102 = Document, 38 = Blog Post
      • Note:  In many cases the contentID is already in the URL, so if you already know the content-type you can derive from just the URL.

     

    Silent Directive for Contents Service

    Call the Jive REST API v3.14 → Content service to get content details without incrementing read counts, which can influence Jive's recommendation engine.  Valid for Jive 8.x, 9.x and Cloud.

    Note:  As of 05/01/2017, this is still an undocumented parameter; however, a ticket has been filed to get it added into the main documentation.

    Example Usage:

    {jiveURL}/api/core/v3/contents/xxxxx?filter=xxxxx&fields=xxxxxxx&directive=silent

     

    Webhooks with Postman

    A nifty contribution share by Matt Collinge

    See: Using Postman to set up Webhooks

     

    Webhooks & Targeting Specific Events

    TODO:  MORE DETAIL / EXAMPLES

     

    See: Webhooks as Add-onsAnatomy of a Webhook and Webhooks service

     

    externalD for External Objects w/Webhook

    TODO:  MORE DETAIL / EXAMPLES

     

    See also: Deconstructing the Jive Derby Integration > Activity Tile for more details on this pattern.

     

    Adding Embedded Images to a Piece of Content

    TODO:  MORE DETAIL / EXAMPLES

     

    1. Upload Image (POST multipart/form-data) See: Images Service
    2. Read Location HTTP Header for API URI for Image
    3. Add HTML Markup in Content Body using the new API URI for the Image, see: Contents Service > Update Content
      • May find value in the Contents Service > Update Editable Content if you want to leverage RTE macros.
        • Note the documentation callout : The input JSON must include a true value in content.editable if the content body is using RTE macros.

     

    Adding Images to User Profiles

    TODO:  MORE DETAIL / EXAMPLES

    Same process, just use different end-points. see: ProfileImage Service and PersonService

     

    Updating a Single Profile Field via PATCH API

    TODO: MORE DETAIL/EXAMPLES

    See also: Updating/Adding/Deleting Select Fields: JSON Patch

     

    Backdating Jive Content w/Activity Suppression

    • Backdate people , places and content (includes comment & message ) timestamps on Jive Objects.
    • Activity is Suppressed for Backdating Operations!
    • Designed for Content Migration Scenarios
    • Using existing APIs, simply pass in a published or updated query parameter with the backdated date.
    • Published only “backdate-able” on CREATE

     

    Example Usage(s):

    POST /api/core/v3/(contents | comments | messages | places)?published=2012-01-31T22%3A46%3A12.044%2B0000&updated=2012-01-31T22%3A46%3A12.044%2B0000

    POST /api/core/v3/(people)?published=2012-01-31T22%3A46%3A12.044%2B0000

    PUT /api/core/v3/( contents | comments | messages | places )/{id}?updated= 2012-02-11T22%3A46%3A12.044%2B0000

    See also: 2014-Q2 Jive Developer Webinar - Recording Now Available where originally announced.

     

    Uploading Asset to Static Service

     

    curl -X POST https://sandbox.jiveon.com/api/core/v3/statics \

      -H 'content-type: multipart/form-data' \

      -F 'json={"filename":"test123.png","placeURI":"https://xxxxx.jiveon.com/api/core/v3/places/xxxxxx","description":"Test File"}' \

      -F file=@test123.png

     

    See Jive API : Unable to upload file to /static