Cisco WebEx Social API Reference Guide, Release 3.3
Tags Resource and TagTrends Resource Operations
Downloads: This chapterpdf (PDF - 250.0KB) The complete bookPDF (PDF - 14.25MB) | Feedback

Tags Resource and TagTrends Resource Operations

Table Of Contents

Tags Resource and TagTrends Resource Operations

Get Information about Tags

Get Tags that are Applied to Posts that are Shared with a Community

Create a Tag

Update the Name of a Tag

Delete a Tag

Get the Number of Times that the Most Common Tags were Applied


Tags Resource and TagTrends Resource Operations


A Cisco WebEx Social tag is keyword or phrase that can be associated with an element such as a post, message, community, and so on. People can use tags to help find elements of interest in Cisco WebEx Social

The Cisco WebEx Social API Tags resource operations let you perform various actions with tags. The TagTrends resource operation lets you determine how many times tags have been applied in Cisco WebEx Social.

For related information, see the operations that the "Add a Tag to a Post" section on page 7-24 and the "Delete a Tag from a Post" section on page 7-25 describe.

Table 8-1 provides a summary of the Tags resource operations. Each operation is described in detail in the section that is listed.

These sections provide this information:

Purpose—Brief explanation of the operation

Availability—Cisco WebEx Social releases that support the operation

Request—HTTP method and URI for the operation

Request Payload—Description of the request payload, if the operation requires one

Response—Description of the expected response when the operation executes

Example—Sample request and response for the operation

Table 8-1 Tags Resource Operations Summary 

Operation and Reference
Purpose

Get Information about Tags

Retrieves information about tags that contain the text that you designate

Get Tags that are Applied to Posts that are Shared with a Community

Retrieves information about the tags that are applied to the posts that are shared with the designated community

Create a Tag

Creates a tag in Cisco WebEx Social

Update the Name of a Tag

Updates the name of the designated tag

Delete a Tag

Deletes the designated tag from Cisco WebEx Social

Get the Number of Times that the Most Common Tags were Applied

Retrieves the number of times that up to 100 of the most common tags were applied in Cisco WebEx Social


Get Information about Tags

Purpose

Retrieves information about tags that contain the text that you designate.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

GET

{http|https}://server[:port]/api/quad/rest/tags?filterBy=name&filterValue=text
[&query_parameters]


where:

server—Host name or IP address of the Cisco WebEx Social server

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

query_parameters—Query parameters. See the "Query Parameters" section for information about using query parameters. For this operation:

The fields query parameter is supported for selecting fields from the Tags resource to include in a response (Table 3-43 describes these fields).

The filterBy query parameter is required as shown in the URI, where text is one or more alphanumeric characters. The space character is not supported. The operation returns all tags that contain the characters that you enter.

The sortOrder query parameter does not apply.

The startIndex query parameter does not apply.

The count query parameter is supported for designating the maximum number of items in the return results.

The meta query parameter does not apply.

Response

Standard response with a response payload that can include one Tags resources (the "Tags Resource" section describes this resource).

Example

Request

GET http://webexsocialserver/api/quad/rest/reporting/tags?filterBy=name&filterValue=foo
Accept:application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "statusCode": 200,
  "startIndex": 0,
  "itemsPerPage": 2,
  "totalResults": 2,
  "filtered": false,
  "sorted": false,
  "entry": [
    {
      "data": {
        "id": 0,
        "name": "foo",
        "resource": "http://quad.cisco.com/schema/1.0/tag",
        "type": null
      }
    },
    {
      "data": {
        "id": 0,
        "name": "food",
        "resource": "http://quad.cisco.com/schema/1.0/tag",
        "type": null
      }
    }
  ],
  "serverMessages": null
}

Get Tags that are Applied to Posts that are Shared with a Community

Purpose

Retrieves information about the tags that are applied to the posts that are shared with the designated community.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

GET

{http|https}://server[:port]/api/quad/rest/tags?filterValue=community_id
&filterBy=@community.posts[&query_parameters]


where:

server—Host name or IP address of the Cisco WebEx Social server.

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

community_id—Cisco WebEx Social identifier of a community for which to obtain shared tags. For information about obtaining the identifier that you need, see the "Identifiers of Cisco WebEx Social Entities" in Cisco API Reference Guide, Release 3.1.

query_parameters

query_parameters—Query parameters. See the "Query Parameters" section for information about using query parameters. For this operation:

The fields query parameter is supported for selecting fields from the TopTag resource to include in a response (Table 3-45 describes these fields)

The filterBy query parameter is required as shown in the URI

The sortOrder query parameter does not apply

The startIndex query parameter is supported for paginating return results

The count query parameter is supported for designating the maximum number of items in the return results

The meta query parameter does not apply

Request Payload

A request payload is not required.

Response

Standard response with a response payload that can include one or more TopTag resources (the "TopTag Resource" section describes this resource).

Example

Request

GET http://webexsocialserver/api/quad/rest/tags?filterValue=82738 
&filterBy=@community.posts
Accept:application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "statusCode": 200,
  "startIndex": 0,
  "itemsPerPage": 3,
  "totalResults": -1,
  "filtered": false,
  "sorted": false,
  "entry": [
    {
      "data": {
        "name": "happy",
        "resource": "http://quad.cisco.com/schema/1.0/toptag",
        "usageCount": 2
      }
    },
    {
      "data": {
        "name": "communitytag",
        "resource": "http://quad.cisco.com/schema/1.0/toptag",
        "usageCount": 1
      }
    },
    {
      "data": {
        "name": "sad",
        "resource": "http://quad.cisco.com/schema/1.0/toptag",
        "usageCount": 1
      }
    }
  ],
  "serverMessages": null
}

Create a Tag

Purpose

Creates a tag in Cisco WebEx Social.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

POST

{http|https}://server[:port]/api/quad/rest/tags


where:

server—Host name or IP address of the Cisco WebEx Social server.

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

Request Payload

The request payload includes fields from the Tags resource (the "Tags Resource" section describes this resource):

Required Fields
Optional Fields

name


Response

Standard response with a response payload that can include one Tags resources (the "Tags Resource" section describes this resource).

Example

Request

POST http://webexsocialserver/api/quad/rest/tags
Content-Type: application/json
Accept: application/json
{"name": "webex"}

Response

Status Code: 201 Created
{
  "statusCode": 200,
  "startIndex": 0,
  "itemsPerPage": 1,
  "totalResults": 1,
  "filtered": false,
  "sorted": false,
  "entry": [
    {
      "data": {
        "followCount": 0,
        "id": 910025,
        "name": "webex",
        "resource": "http://quad.cisco.com/schema/1.0/tag",
        "type": null
      }
    }
  ],
  "serverMessages": null
}

Update the Name of a Tag

Purpose

Updates the name of the designated tag.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

PUT

{http|https}://server[:port]/api/quad/rest/tags/name


where:

server—Host name or IP address of the Cisco WebEx Social server.

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

name—Name of the tag to update.

Request Payload

The request payload includes fields from the Tags resource (the "Tags Resource" section describes this resource):

Required Fields
Optional Fields

name


Response

Standard response (see the "API Responses" section) with an HTTP header only.

Example

Request

PUT http://webexsocialserver/api/quad/rest/tags/webex
Content-Type: application/json
Accept: application/json
{"name": "webex"}

Response

204 No Content

Delete a Tag

Purpose

Deletes the designated tag from Cisco WebEx Social.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

DELETE

{http|https}://server[:port]/api/quad/rest/tags/name


where:

server—Host name or IP address of the Cisco WebEx Social server.

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

name—Name of the tag to delete.

Request Payload

A request payload is not required.

Response

Standard response (see the "API Responses" section) with an HTTP header only.

Example

Request

DELETE http://webexsocialserver/api/quad/rest/tags/webex

Response

HTTP/1.1 204 No Content

Get the Number of Times that the Most Common Tags were Applied

Purpose

Retrieves the number of times that up to 100 of the most common tags were applied in Cisco WebEx Social.

Availability

Cisco WebEx Social 3.3 and later.

Request

HTTP Method
URI

GET

{http|https}://server[:port]/api/quad/rest/reporting/tagtrends[?query_parameters]


where:

server—Host name or IP address of the Cisco WebEx Social server

port—Port number on which the Cisco WebEx Social server listens for API requests. Required if the port number is not 80.

query_parameters—Query parameters. See the "Query Parameters" section for information about using query parameters. For this operation:

The fields query parameter is supported for selecting fields from the TagTrends resource to include in a response (Table 3-44 describes these fields).

The filterBy query parameter is not supported for filtering resources in a response.

The sortOrder query parameter does not apply.

The startIndex query parameter does not apply.

The count query parameter determines the number of tags about which to return information. For example, if you specify count=3, the three most common tags are returned. Valid values are integers 0 through 100. The default value is 25. The system returns information about the tags in the order of how often they were applied, beginning with the tag that was applied most often.

The meta query parameter does not apply.

The special query parameter startTime designates the beginning of the period that the system considers for the return results, in UTC format. For example 1332720000000 indicates March 26, 2012, 00:00:00 GMT. The default start time is January 1, 1970.

The special query parameter endTime designates the end of the period that the system considers for the return results, in UTC format. 1332806400000 indicates March 27, 2012, 00:00:00 GMT. The default end time is the time at which you execute this operation.

Response

Standard response with a response payload that can include one TagTrends resources (the "TagTrends Resource" section describes this resource).

Example

Query

GET http://webexsocialserver/api/quad/rest/reporting/tagtrends?count=3
Accept:application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "statusCode": 200,
  "startIndex": 0,
  "itemsPerPage": 1,
  "totalResults": 1,
  "filtered": false,
  "sorted": false,
  "entry": [
    {
      "data": {
        "endTime": 1364418349597,
        "numsTags": 3,
        "resource": "http://quad.cisco.com/schema/1.0/tagtrends",
        "startTime": 0,
        "topTags": [
          {
            "resource": "http://quad.cisco.com/schema/1.0/toptag",
            "name": "portal",
            "usageCount": 3
          },
          {
            "resource": "http://quad.cisco.com/schema/1.0/toptag",
            "name": "qa support",
            "usageCount": 2
          },
          {
            "resource": "http://quad.cisco.com/schema/1.0/toptag",
            "name": "defect",
            "usageCount": 1
          }
        ]
      }
    }
  ],
  "serverMessages": null
}