How to: The Basics of using Jive's REST API

Version 4

     

    Summary

    The Jive REST API provides exhaustive functionalities for interacting with your Jive community. This KB gives you a step-by-step guide on how to use the web service endpoints to perform certain functionalities, like searching for content or creating a new user.

     

    Versions

    • Verified for version: Jive, Jive Custom 6, 7

     

    Using curl

    curl is a command line tool that you can use to consume web services. Here's a general syntax:

    curl -X GET "<jiveURL>/api/core/v3/<service>/<resource>?<parm1=value1>&<parm=value2>" --basic --user <username>:<password>

                  
    • curl uses basic authentication by default, so you can leave off "--basic" if you like
    • curl uses GET by default, so you can leave off "-X GET" if you want to. Replace it with "-X POST" or  "-X PUT" depending on the rest call.
    • add -v if you need verbose output (full headers and such)
    • add -o <file> to save the output in a file

     

    To get information on user with username test, while logged in as user jive with password jetLee, you'd need to do:

    curl --user jive:jetLee "http://jive.localhost.com:8888/api/core/v3/people/username/test"

                 

    and a more complex example on how to create a subspace using curl:

    curl --user jive:jetLee --verbose --header "Accept: application/json" --header "Content-type: application/json" --request POST --data '{  "contentTypes" : [ "blog", "discussions", "documents", "projects" ],  "displayName" : "APINewBieSpace",  "name" : "APINewBieSpace",  "parent" : "http://jive.localhost.com:8888/api/core/v3/places/1006",  "type" : "space" }' http://jive.localhost.com:8888/api/core/v3/places

                 

    Using REST client

    You will need to use a REST client application on your computer to run these API calls.  There are a variety of REST client tools available: Many Google Chrome users prefer the Postman extension. We will be using RESTclient extension for Firefox for this guide.

    Configuring the RESTClient

     

    • Download and install RESTClient add-on for Firefox
    • At the top of your web browser, click the RESTClient icon   . If you do not see the RESTClient icon, you can click Tools > RESTClient instead.

      RESTClient.jpg

    • Navigate to Authentication > Basic Authentication. The login window appears; enter username and password and click the Okay button

        RESTClient2.jpg

    • Navigate to Headers > Custom Header. The Request Header window appears; enter the Name and Value as shown below:

        RESTClient3.jpg

    • Now the Headers Pane of your RESTClient should look like this:

        RESTClient4.jpg

    So to search contents in your community with respect to creation date, Select GET as the Method, and in the URL section, enter:

    <jiveURL>/api/core/v3/search/contents?sort=updatedDesc&filter=after(2014-01-31T19:13:29.851+0000)&filter=search(newbie,api+tutorial)

                 

    Then click the SEND button:

    RESTClient5.jpg

    Notes:

    • A search filter  "filter=search(<search_term>)" must be specified whilst searching/filtering contents on the search/contents endpoint. This is not explicitly stated in the API documentation.
    • Search terms are separated by commas
    • Compound search terms are concatenated by a plus, for example "api tutorial" should be passed as "api+tutorial" (without the quotes)
    • The Response headers tab displays the status of your Request
    • The Response Body tab displays the result of your GET request

    A more complex example to create a user account via the RESTclient is described below:

    Select POST method, in the URL section, enter:

    <jiveURL>/api/core/v3/people

    In the body section, enter:

    {

          "emails" : [ {

              "value" : "jetme@gmail.com",

              "type" : "work",

              "primary" : true,

              "jive_label" : "Email"

          } ],

          "jive" : {

              "password" : "4Jive",

              "username" : "jetme"

          },

          "name" : {

          "familyName" : "Lee",

          "givenName" : "Jet"

          }

      }

                

     

    Then click the SEND button:

    RESTClient7.jpg

     

    You will see a "201 Created" status code in the Response section - This tells you that the creation was successful.

     

    Reference

    jive-ask-a-question.png?a=145945776139