Content

Content Service

Web service endpoints for functionality that is common to all content objects.

Supported content types are:

  • discussion (Discussion) - a discussion, which is the beginning of a conversation.
  • document (Document) - a document in Jive that can be discussed and shared with other people.
  • file (File) - a file in Jive that can be discussed and shared with other people.
  • poll (Poll) - a poll where people can vote to make a decision or express an opinion.
  • post (Post) - an entry in a blog.
  • favorite (Favorite) - a link to content around the web that can be shared and discussed.
  • task (Task) - a task for a person to get things done.
  • update (Update) - a user status update.

Plugins can add more content types to the above list.

Examples:
Create Discussion

POST to /contents to create a Discussion. Here is an example using curl.

curl -u mary:password -H "Content-Type: application/json" --data '{ "type": "discussion", "content": { "type": "text/html", "text":"Starting a discussion"}, "subject": "A new discussion"}' http://example.jiveon.com/api/core/v3/contents

Create Update

Updates can be created using the contents endpoint. The update will be for the user whose credentials are used. Example with curl of creating a status update.

curl -u bob:password -H "Content-Type: application/json" --data '{ "type": "update", "content": { "type": "text/html", "text":"Vacation coming up soon!"}, "subject": "Vacation"}' http://example.jiveon.com/api/core/v3/contents

Create Repost

Having created an update, you can create a "repost", or an update that quotes your original update. Here, in the "repost" field you must provide the URI of the original update returned in the response of the previous example.

curl -u bob:password -H "Content-Type: application/json" --data '{ "type": "update", "repost": "http://example.jiveon.com/api/core/v3/contents/1234", "content": { "type": "text/html", "text":"Still can't wait for the vacation!"}, "subject": "Vacation"}' http://example.jiveon.com/api/core/v3/contents

Create Comment

POST /contents/{contentID}/comments

Create a new comment as a reply to the specified content object. The parent field (if any) in the incoming entity will be ignored. Instead, it will be set to the URI of the specified content object.

Path Parameters:
NameTypeRequiredDescription
contentIDStringtrueID of the content object this comment replies to
Query Parameters:
NameTypeRequiredDescription
authorBooleanfalseFlag indicating if new comment is an author comment or a regular comment (only valid for documents). By default a regular comment will be created.
fieldsStringfalseFields to include in the returned Comment
Takes:
  • Comment describing the comment to be created
    • Retrieves:
  • Comment representing the newly created comment
    • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    409 (Conflict)You attempt to add a comment to a content object that does not support them, or for which comments have been closed
    403 (Forbidden)You are not allowed to perform this operation
    404 (Not Found)The specified parent content object (or comment) cannot be found

    Create Content

    POST /contents

    Create a new content object with specified characteristics, and return an entity representing the newly created content object.

    For those types of content that support attachments, it is possible to specify URL of files that the server will download and store them as attachments of the new content. A BAD_REQUEST error will be returned if URL of files are passed and the content type does not support attachments. Here we can see an example where attachments are specified as URLs.

     {
 "content":{
 "type":"text/html",
 "text":"<body><p>Some interesting text</p></body>"
 },
 "subject":"New Document",
 "type":"document",
 "attachments":[
 {
 "doUpload":true,
 "url":"http://www.mysite.com/images/cat.jpg"
 }
 ]
 }

    Attachments can only be images when creating Update. Those images will be accessible through the images resource of an Update.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
    • For all content object types, the content and subject fields are required. Furthermore, subject must be unique within the parent place.
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to include in the returned entity
    Takes:
  • A Content describing the content object to be created
    • Retrieves:
  • Content representing the newly created content
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content

    Upload New Content

    POST /contents

    Create a new content object with specified characteristics, and return an entity representing the newly created content object. Uploaded files will be added to the new content object as attachments. Uploading attachments is only allowed for those content types that support attachments. A BAD_REQUEST error will be returned if attachments are passed and the content type does not support them.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
    • For all content object types, the author, content, parent, and subject fields are required, and must be unique within the parent place.
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to include in the returned entity
    Takes:
  • A multipart of subtype form-data that will include a section with a Content describing the content to be created and another section for each file being uploaded.
    • Retrieves:
  • Content representing the newly created content
    • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content

    Create Content Like

    POST /contents/{contentID}/likes

    Register that the requesting person likes the specified content object.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be liked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access or like this content object
    404 (Not Found)The specified content object does not exist

    Destroy Content

    DELETE /contents/{contentID}

    Delete the specified content object.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified content object
    404 (Not Found)The specified content does not exist

    Destroy Content Like

    DELETE /contents/{contentID}/likes

    Delete the like of the specified content object by the requesting user.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueThe ID of the content object for which a like is being removed
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)You do not currently have a like registered for this content object
    403 (Forbidden)You are not allowed to access or unlike this content object
    404 (Not Found)The specified content object does not exist

    Get Comments

    GET /contents/{contentID}/comments

    Return a paginated list of comments to the specified content object, optionally limiting the returned results to direct replies only. The specified content object type must support comments, or be a comment itself (in which case replies to this comment only are returned).

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object for which to return comments
    Query Parameters:
    NameTypeRequiredDescription
    excludeRepliesBooleanfalseFlag indicating whether to exclude replies (and therefore return direct comments only)
    hierarchicalBooleanfalseFlag indicating that comments should be returned in hierarchical order instead of chronological order
    authorBooleanfalseFlag indicating if author comments should be returned or regular comments (only valid for documents). By default regular comments are returned.
    startIndexIntegerfalseZero-relative index of the first comment to be returned
    countIntegerfalseMaximum number of comments to be returned
    anchorStringfalseoptional URI for a comment to anchor at. Specifying a anchor will try to return the page containing the anchor. If the anchor could not be found then the first page of comments will be returned.
    fieldsStringfalseFields to be returned in the selected comments
    Retrieves:
  • Comment[]
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified content object or comments
    404 (Not Found)The specified content object does not exist
    501 (Not Implemented)The specified content object is of a type that does not support comments

    Get Content

    GET /contents/{contentID}

    Return the specified content object with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content containing the specified content
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified content object
    404 (Not Found)The specified content does not exist

    Get Content Followers

    GET /contents/{contentID}/followers

    Return a paginated list of Persons about people who are following the specified content.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to check for followers
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first instance to be returned
    countIntegerfalseMaximum number of instances to be returned (i.e. the page size)
    fieldsStringfalseFields to be returned (or null for summary fields)
    Retrieves:
  • Person listing people following the specified content
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)The request criteria are malformed
    403 (Forbidden)The requesting user is not authorize to retrieve this user information
    404 (Not Found)The specified user cannot be found
    Since: 3.5

    Get Content Following In

    GET /contents/{contentID}/followingIn

    Return the list of custom streams in which the requesting user is following this content object.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to check for following
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be included in the returned representation
    Retrieves:
  • Stream[] listing the streams in which the requesting user is following this object
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this content object
    404 (Not Found)The specified content object does not exist

    Get Content Likes

    GET /contents/{contentID}/likes

    Return a paginated list of the people who like the specified content object.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object for which to return liking people
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first person to be returned
    countIntegerfalseMaximum number of people to be returned
    fieldsStringfalseFields to be returned on liking people
    Retrieves:
  • Person[] listing people who like the specified content object
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this content object
    404 (Not Found)The specified content object does not exist

    Get Contents

    GET /contents

    Return a paginated list of content objects that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    author one or more person URIs, separated by commas ?filter=author(http://domain/api/core/v3/people/12,http://domain/api/core/v3/people/853)
    entityDescriptor one or more objectType,objectID pairs (this filter is likely only useful to those developing the Jive UI itself). This filter cannot be combined with other filters. ?filter=entityDescriptor(102,1234,37,2345)
    place only one place URI where the content lives ?filter=place(http://domain/api/core/v3/places/1006)
    relationship Chose one of the following options:
    • participated - Returns content where the authenticated user participated in
    • following - Returns content that the authenticated user is following
    • recentlyviewed - Returns content that the authenticated user recently viewed
    This filter cannot be combined with filters: status. Available since 3.3.     		?filter=relationship(participated)
    search One or more search terms, separated by commas. You must escape any of the following special characters embedded in the search terms: comma (","), backslash ("\"), left parenthesis ("("), and right parenthesis (")") by preceding them with a backslash. ?filter=search(test,report) or ?filter=search(10\,000)
    status Returns content that is in draft mode and the authenticated user can see. This filter cannot be combined with filters: relationship. Available since 3.3. ?filter=status(draft)
    tag one or more tags, separated by commas (matching any tag will select a content). Replace the , with AND if you want to retrieve content that has all the specified tags. ?filter=tag(sales,performance) or ?filter=tag(sales%20AND%20performance)
    type one or more object types of desired contained content objects separated by commas ?filter=type(document,discussion)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this content object was created, in ascending order
    dateCreatedDesc Sort by the date this content object was created, in descending order. Default if none was specified.
    latestActivityAsc Sort by the date this content object had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this content object had the most recent activity, in descending order
    titleAsc Sort by content object subject, in ascending order

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseThe filter criteria used to select content objects
    sortStringfalseThe requested sort order
    startIndexIntegerfalseThe zero-relative index of the first matching content to be returned
    countIntegerfalseThe maximum number of contents to be returned
    fieldsStringfalseThe fields to be returned on each content
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed

    Get Popular Content

    GET /contents/popular

    Return a list of popular content objects for the authenticated user. Use this service when recommendation is disabled. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseThe fields to be returned on each content
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access the specified content object
    Since: 3.1

    Get Recent Content

    GET /contents/recent

    Return a list of recently updated content objects that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    place only one place URI where the content lives ?filter=place(http://domain/api/core/v3/places/1006)
    type one or more object types of desired contained content objects separated by commas ?filter=type(document,discussion)

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseThe filter criteria used to select content objects
    startIndexIntegerfalseThe zero relative index of the first content object to be returned
    countIntegerfalseThe maximum number of content objects to be returned
    fieldsStringfalseThe fields to be returned on each content object
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified content object
    410 (Gone)Recommendation feature is disabled
    404 (Not Found)The specified place in the filter does not exist
    Since: 3.1

    Get Recommended Content

    GET /contents/recommended

    Return a list of recommended content objects for the authenticated user. When recommender service is not enabled in the Jive instance then predefined recommended content is going to be returned instead. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    countIntegerfalseThe maximum number of contents to be returned
    fieldsStringfalseThe fields to be returned on each content
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access the specified content object
    Since: 3.1

    Get Trending Content

    GET /contents/trending

    Return a list of trending content objects that match the specified filter criteria. It's possible for some Jive instances to have recommendation disabled, for these cases use getPopularContent(fields, abridged) instead. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    place only one place URI where the content lives ?filter=place(http://domain/api/core/v3/places/1006)
    type one or more object types of desired contained content objects separated by commas ?filter=type(document,discussion)

    The returned list may contain a mixture of content entities of various types. On any given content object entity, use the type field to determine the type of that particular content.

    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseThe filter criteria used to select content objects
    countIntegerfalseThe maximum number of contents to be returned
    fieldsStringfalseThe fields to be returned on each content
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Retrieves:
  • Content[] of the matched content objects
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified content object
    410 (Gone)Recommendation feature is disabled
    404 (Not Found)The specified place in the filter does not exist
    Since: 3.1

    Mark Read

    POST /contents/{contentID}/read

    Mark the specified content object as having been read.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be marked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    403 (Forbidden)You are not allowed to access this content object
    404 (Not Found)The specified content object does not exist

    Mark Unread

    DELETE /contents/{contentID}/read

    Mark the specified content object as having not been read.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be marked
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field was malformed
    403 (Forbidden)You are not allowed to access this content object
    404 (Not Found)The specified content object does not exist

    Create Content Following In

    POST /contents/{contentID}/followingIn

    Replace the list of Streams in which the requesting user is following this content object.

    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object being followed
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the updated list of streams
    Takes:
  • JSON array of Stream objects or URIs
    • Retrieves:
  • Stream[] updated list of streams
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)if any input field is malformed
    404 (Not Found)if the specified person does not exist
    Since: 3.3

    Update Content

    PUT /contents/{contentID}

    Update an existing content with specified characteristics.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
    • For all content object types, the author, content, parent, and subject fields are required, and must be unique within the parent place.
    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be updated
    Query Parameters:
    NameTypeRequiredDescription
    minorBooleanfalseFlag indicating whether this update is a minor edit (true) or not (false)
    fieldsStringfalseFields to include in the returned entity
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Takes:
  • Content describing the content to be updated
    • Retrieves:
  • Content representing the updated content object
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two content objects of the same type with the same subject)
    403 (Forbidden)You are not allowed to access the specified content object, or to make the requested change in content object state

    Upload Update Content

    PUT /contents/{contentID}

    Update an existing content with specified characteristics including the option to replace existing attachments. Uploading attachments is only allowed for those content types that support attachments. A BAD_REQUEST error will be returned if attachments are passed and the content type does not support them.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all content object types, the following fields are processed: author, content, parent, status, subject, tags, type.
    • For all content object types, the author, content, parent, and subject fields are required, and must be unique within the parent place.
    Path Parameters:
    NameTypeRequiredDescription
    contentIDStringtrueID of the content object to be updated
    Query Parameters:
    NameTypeRequiredDescription
    minorBooleanfalseFlag indicating whether this update is a minor edit (true) or not (false)
    fieldsStringfalseFields to include in the returned entity
    abridgedBooleanfalseFlag indicating that if content.text is requested, it will be abridged (length shortened, HTML tags removed)
    Takes:
  • Multipart of subtype form-data that will include a section with a Content describing the content to be updated and another section for each file being uploaded.
    • Retrieves:
  • Content representing the updated content object
    • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two content objects of the same type with the same subject)
    403 (Forbidden)You are not allowed to access the specified content object, or to make the requested change in content object state