REST V3 API - Tips & Tricks

Document created by Ryan Rutan on Jun 7, 2017Last modified by Ryan Rutan on Sep 15, 2017
Version 8Show Document
  • View in full screen mode

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.aurea.com/api/core/v3/people/@me"

curl -v -k --header "Content-Type: application/json" --header "Authorization: Bearer YOUR_TOKEN_VALUE" "https://community.aurea.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.aurea.com/api/core/v3/contents/1188411?fields=-resources  - Blanket kill all resources for the piece of content

https://community.aurea.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.aurea.com/api/core/v3/contents/1188411?fields=subject,author.displayName,resources.self,-author…  - Only a specific resource field and specific child attributes

https://community.aurea.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.aurea.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.aurea.com/docs/DOC-233174/api/v3

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

https://community.aurea.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.aurea.com/api/core/v3/contents?filter=entityDescriptor(102,233174) - This Document

https://community.aurea.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 mcollinge

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

Attachments

    Outcomes