Cisco WebEx Social API Reference Guide, Release 3.1
Introduction to the Cisco WebEx Social API
Downloads: This chapterpdf (PDF - 338.0KB) The complete bookPDF (PDF - 16.07MB) | Feedback

Introduction to the Cisco WebEx Social API

Table Of Contents

Introduction to the Cisco WebEx Social API

Cisco WebEx Social API Overview

Cisco WebEx Social API Operations Summary

API Resources

Data Formats

API Requests

HTTP Methods

Identifiers of Cisco WebEx Social Entities

Request Payloads

API Responses

Response with HTTP Header Only

Response with Payload

HTTP Status Codes

Server Messages

Query Parameters


Introduction to the Cisco WebEx Social API


This chapter provides an overview of the Cisco WebEx Social application programming interface (API) and provides general information that applies to the API operations.

This chapter includes these topics:

Cisco WebEx Social API Overview

Cisco WebEx Social API Operations Summary

API Resources

Data Formats

API Requests

API Responses

Query Parameters

Cisco WebEx Social API Overview

The Cisco WebEx Social API is a Representational StateTransfer (REST)-based set of operations that provide secure and authenticated access to and management of Cisco WebEx Social resources and entities. With the API, you can retrieve, create, update, and delete Cisco WebEx Social resources and entities. You also can search for, filter, and sort items.

The Cisco WebEx Social API operations are arranged in these categories:

User resource operations—Operations for obtaining information about Cisco WebEx Social users and performing various operations with users

Community resource operations—Operations for obtaining information about Cisco WebEx Social communities and performing various actions with communities

Membership Request resource operations—Operations for retrieving and updating requests for community membership

Post resource operations—Operations for obtaining information about posts and performing various actions with posts

Document File resource operations—Operations for obtaining information about document files and performing various actions with document files

Document Folder resource operations—Operations for obtaining information about document folders and performing various actions with document folders

File resource operations—Operations for embedding an image in a post, attaching a file to a post or a micropost, and managing an image or file

Configuration operation—Operation for obtaining information about configurable settings for Cisco WebEx Social clients

Mobile Client operations—Operations for obtaining information that relates to mobile clients

API Consumer resource operations—Operations for managing Cisco WebEx Social API consumers when using OAuth 1a for authorization and authentication

API Client resource operation—Operations for managing Cisco WebEx Social API consumers when using OAuth 2 for authorization and authentication

Search operation—Operation for searching for content, users, and communities throughout Cisco WebEx Social

The Cisco WebEx Social API supports these protocols for authorization, authentication, and security:

OAuth—Provides authentication for API requests that come from API consumers

xAuth—Provides authentication for API requests that come from trusted devices and applications

SSO—If Cisco WebEx Social is configured with a single sign-on (SSO) provider, an SSO token must be included in an HTTP header

The Advanced Portal Properties area in the Portal page of the Director includes properties that control the operation of the Cisco WebEx Social API. For more information, see the "Advanced Portal Properties for the Cisco WebEx Social API" section in the "Director" chapter in Cisco WebEx Social Administration Guide.

Cisco WebEx Social API Operations Summary

Table 1-1 provides a summary of the Cisco WebEx Social API operations. Each operation is described in detail in the section that is listed.

In this table, "you," "your," and "yourself" refer to the authenticated user who is executing an operation.

Table 1-1 Cisco WebEx Social API Operations Summary 

Operation and Reference
Purpose

User Resource Operations

Get Information about Yourself

Retrieves information about you

Get Information about a User

Retrieves information about the designated user

Get Information about Users

Retrieves information about the designated users

Get Information about a User with the Designated E-mail Address or Screen Name

Retrieves information about the user with the designated e-mail address or Cisco WebEx Social screen name

Update Information for a User

Updates information for the designated user

Get Information about Your Profile Images

Retrieves information about your Cisco WebEx Social profile images

Get Information about the Profile Images of a Designated User

Retrieves information about the Cisco WebEx Social profile images of the designated user

Upload Profile Image for Yourself

Uploads your Cisco WebEx Social profile image

Get Information about Communities to which You Belong

Retrieves information about communities to which you belong

Get Information about Communities to which a User Belongs

Retrieves information about all communities to which the designated user belongs

Get Information about Communities that are Visible on Your Profile

Retrieves information about communities that are visible on your profile

Get Information about Communities that are Visible on the Profile of a User

Retrieves information about communities that are visible on the profile of the designated user

Get Information about Posts that are Visible on Your Profile

Retrieves information about all posts that are visible on your profile

Get Information about Posts that are Visible on the Profile of a User

Retrieves information about all posts that are visible on the profile of the designated user

Get Information about Posts that are in Your Library

Retrieves information about all posts that are in your library

Get Information about Recent Posts that are in Your Library

Retrieves information about posts that are in your library and that have been posted within the past 2 weeks, excluding posts that you made

Get Information about Posts that are Visible on the Profile of a User

Retrieves information about all posts that are visible on the profile of the designated user

Get Information about the Latest Micropost that You Made

Retrieves information about the latest micropost that you made

Get Information about the Latest Micropost that a User Made

Retrieves information about the latest micropost that the designated user made

Get Information about Posts that You have Marked as Favorites

Retrieves information about Favorite resources that have as the destination the posts that you have marked as favorites

Get Information about Posts that a User has Marked as Favorites

Retrieves information about Favorite resources that have as the destination the posts that the designated user has marked as favorites

Get Information about Your Document Library

Retrieves information about your document library

Get Information about the Document Library of a User

Retrieves information about the document library of a designated user

Get Information about Document Files in Your Document Library

Retrieves information about all documents that are in your document library

Get Information about Document Files in Your Document Library that are Authored by You

Retrieves information about document files that are in your document library and that are authored by you

Get Information about Document Files in Your Document Library that are Authored by a Designated User

Retrieves information about document files that are in your document library and that are authored by the designated user

Get Information about Document Files in the Document Library of a User

Retrieves information about all document files that are in the document library of the designated user

Get Information about Document Files in the Document Library of a User that are Authored by the Designated User

Retrieves information about document files that are in the document library of the designated user and that are authored by the designated user

Get Information about the Designated Custom Attributes of a User

Retrieves information about the designated custom attributes of the designated user

Get Information about All Custom Attributes of a User

Retrieves information about all custom attributes of the designated user

Update Custom Attributes of a User

Updates designated custom attributes for the designated user

Get Information about All Activities that are Visible to You

Retrieves information about all activities that are visible to you in Cisco WebEx Social

Get Information about All Activities that Appear in Your Watch List

Retrieves information about all activities that appear in your Cisco WebEx Social watch list

Get Information about all Activities that Appear in the Profile Page of a User

Retrieves information about all activities that appear in the profile page of the designated user

Create a Favorite Relationship for Yourself

Creates a favorite relationship between you and a Cisco WebEx Social post

Remove a Favorite Relationship for Yourself

Removes the designated favorite relationship in which you favorited a Cisco WebEx Social post

Create a Follow Relationship for Yourself

Creates a follow relationship for yourself in which you are following another Cisco WebEx Social user

Get Information about Users that are Following You

Retrieves Follow resources that have as the destination the users that are following you

Get the Number of Users that are Following You

Retrieves the number of users that are following you

Get Information about Users that are Following the Designated User

Retrieves Follow resources that have as the destination the users that are following the designated user

Get the Number of Users that are Following the Designated User

Retrieves the number of users that are following the designated user

Get Information about Users that You are Following

Retrieves Follow resources that have as the destination the users that you are following

Get the Number of Users that You are Following

Retrieves the number of users that you are following

Get Information about Users that the Designated User is Following

Retrieves Follow resources that have as the destination the users that the designated user is following

Get the Number of Users that the Designated User is Following

Retrieves the number of users that the designated user is following

Remove Your Following of Another Cisco WebEx Social User

Remove the designated follow relationship in which you are following another Cisco WebEx Social user

Get Information about Users that You and the Designated User Both are Following

Retrieves Follow resources that have as the destination the users you and a designated user both are following

Get the Number of Users that You and the Designated User Both are Following

Retrieves the number of users that you and a designated user both are following

Create a Like Relationship for Yourself

Creates a like relationship in which you like a Cisco WebEx Social post

Remove a Like Relationship for Yourself

Removes the designated like relationship in which you like a Cisco WebEx Social post

Community Resource Operations

Get Information about a Community

Retrieves information about the designated community

Get Information about Communities

Retrieves information about communities that are visible to you

Create a Community

Creates a community

Update a Community

Updates the designated community

Delete a Community

Deletes the designated community from Cisco WebEx Social

Add Yourself to a Community

Adds you to the designated community

Remove Yourself from a Community

Removes you from the designated community

Add a User to a Community

Adds the designated user to the designated community

Add a User to a Community (Alternate Method)

Adds the designated user to the designated community

Remove a User from a Community

Removes the designated user from the designated community

Remove a User from a Community (Alternate Method)

Removes the designated user from the designated community

Assign the Community Owner Role to a User

Assigns the Community Owner role to the designated user for the designated community

Remove the Community Owner Role from a User

Removes the Community Owner role from the designated user for the designated community

Get Information about Users Assigned to a Community

Retrieves information about users that are assigned to the designated community

Get Information about Users Assigned to a Community (Alternate Method)

Retrieves information about users that are assigned to the designated community

Add a User Group to a Community

Adds the designated user group to the designated community

Remove a User Group from a Community

Removes the designated user group from the designated community

Assign the Community Owner Role to Users in a User Group

Assigns the Community Owner role to the users in the designated user for the designated community

Remove the Community Owner Role from Users in a User Group

Removes the Community Owner role from the users in the designated user for the designated community

Get Information about User Groups Assigned to a Community

Retrieves information about user groups that are assigned to the designated community

Get Information about a Community Category

Retrieves information about the designated community category

Get Information about Community Categories

Retrieves information about community categories

Get Community Types that a Community Category Supports

Retrieves the community types that the designated community category supports

Get Information about Membership Requests for a Community

Retrieves information about membership requests that have been made to the designated community

Get Code of Conduct

Retrieves the Cisco WebEx Social community code of conduct

Get Information about Posts for a Community

Retrieves information about all posts that have been shared with the designated community

Get Information about Questions and Answers for a Community

Retrieves information about questions and answers that were submitted when the designated community was created

Get Information about the Document Library of a Community

Retrieves information about the document library of a designated community

Get Information about Document Files in the Document Library of a Community

Retrieves information about all document files that are in the document library of the designated community

Get Information about Document Files in the Document Library of a Community that are Authored by a Designated User

Retrieves information about document files that are in the document library of the designated community and that are authored by the designated user

Get Information about Community Profile Images

Retrieves information about profile images for the designated community

Get All Activities that are Visible to You in a Community

Retrieves information about all activities that are visible to you in the designated community

Update a Community Profile Image

Updates the community profile image for the designated community

Membership Request Resource Operations

Get Information about a Membership Request

Retrieves information about the designated membership request

Update a Membership Request

Updates the designated membership request

Post Resource Operations

Create a Post

Creates a new Cisco WebEx Social post

Get Information about a Post

Retrieves information about the designated post

Get Information about Posts

Retrieves information about one or more posts

Update Information about a Post

Updates information about the designated post

Get Information about Attachments for a Post

Retrieve information about all attachments for the designated post

Add Attachments to a Post

Adds attachments to the designated post

Delete Attachments from a Post

Deletes all attachments from the designated post

Get Information about a Comment for a Post

Retrieves information about the designated comment for the designated post

Get Information about Comments for a Post

Retrieves information about the comments that have been added to the designated post

Create a Comment for a Post

Creates a comment for the designated post and adds the comment to the post

Update a Comment for a Post

Updates the designated comment for the designated post

Delete a Comment from a Post

Deletes the designated comment from the designated post

Get Permissions for a Post

Retrieves the permissions that have been assigned to the designated post

Update Permissions for a Post

Updates permissions for the designated post

Get Users that have Marked a Designated Post as a Favorite

Retrieves Favorite resources that have as the destination the users that have marked the designated post as a favorite

Get Information about Users that Like a Designated Post

Retrieves Like resources that have as the destination the users that like the designated post

Get the Number of Users that Like a Designated Post

Retrieves the number of Like resources that have as the destination the users that like the designated post

Document File Resource Operations

Get Information about the Current Version of a Document File

Retrieves information about the current version of the designated document file

Get Information about the Designated Version of a Document File

Retrieves information about the designated version of the designated document file

Get Information about All Versions of a Document File

Retrieves information about all versions of the designated document file

Upload a Document File

Uploads the designated document file to the designated folder

Update Information about a Document File

Updates information about the designated document file

Delete all Versions of a Document File

Deletes the designated version of the designated document file from the document folder that contains it

Delete the Designated Version of a Document File

Deletes all versions of the designated document file from the document folders that contain them

Document Folder Resource Operations

Get Information about a Document Folder

Retrieves information about the subfolders and document files that are in a designated document folder

Create a Document Folder

Creates a document folder in the designated user library or designated community library

Update Information about a Document Folder

Updates Information about the designated document folder

Delete the Designated Document Folder

Deletes the designated document folder

File Resource Operations

Get Information about a File

Retrieves information about the designated file

Upload a File

Uploads to the Cisco WebEx Social server the image to be embedded in a post or the file to be attached to a post or micropost

Delete a File

Deletes the designated file from the Cisco WebEx Social server

Configuration Operation

Get Information about Configurable Settings for Cisco WebEx Social Clients

Retrieves information about configurable settings for Cisco WebEx Social clients

Mobile Client Operations

Get Information about a Mobile Client Device Type

Retrieves information about a designated Cisco WebEx Social mobile client device type

Get Information about Custom Applications that are Supported for a Mobile Client Device Type

Retrieves information about custom applications that are supported for a designated mobile client device type

API Consumer Resource Operations

Get Information about an API Consumer

Retrieves information about the designated API consumer

Get Information about All API Consumers

Retrieves information about each API consumer that has registered with Cisco WebEx Social

Add an API Consumer

Creates a profile in Cisco WebEx Social for an API consumer

Update the Designated API Consumer

Updates the designated API consumer

API Client Resource Operations

Register an API Client

Creates a profile in Cisco WebEx Social for an API client

Search Operation

Search Operation

Provides options for searching for content, users, and communities throughout Cisco WebEx Social


API Resources

A Cisco WebEx Social API resource is a representation of a Cisco WebEx Social entity, such as a user, community, post, and so on, or a representation of a component of a Cisco WebEx Social activity. Each representation is defined by a resource model, which is a schema that is composed of a set of fields that contain information about the entity.

For detailed information about resources, see Chapter 3 "Resources."

Data Formats

The Cisco WebEx Social API supports JSON and XML formats for most requests and responses. The following API operations also support the Atom format for responses:

Get Information about Posts that are Visible on Your Profile

Get Information about Posts that are in Your Library

Get Information about Recent Posts that are in Your Library

Get Information about Posts that are Visible on the Profile of a User

Get Information about Posts for a Community

Get Information about Posts

Get Information about All Activities that are Visible to You

Get Information about All Activities that Appear in Your Watch List

Get Information about all Activities that Appear in the Profile Page of a User

Get All Activities that are Visible to You in a Community

Search Operation, page 12-1

In an operation supports XML, XML is the default format for data that is returned.

The following API operations require the multipart/form-data format for request payload content:

Upload Profile Image for Yourself

Update a Community Profile Image

Upload a File

Add Attachments to a Post

API Requests

An API request consists of an HTTP method and a URI. The HTTP method designates the type of activity to perform. Operations use standard HTTP methods to retrieve, update, create, and delete resources or data. The URI identifies the resource or resources that the request targets, and can include various parameters to further refine the operation.

Most API requests require that an HTTP Accept header be included. In addition, PUT and POST requests require an HTTP Content-Type header. The Accept header can specify xml or json, depending on the operation. The Content-Type header can specify xml, json, atom+xml, or multipart/form-data, depending on the operation. (See the "Data Formats" section for more information about supported formats.)

If Cisco WebEx Social is configured with an SSO provider, an SSO token must be included as an HTTP header.

You also can include the optional Accept-Encoding:gzip header, which compresses the response payload.

To invoke an API operation, you send an HTTP request from any client that supports the creation of such a request to a Cisco WebEx Social server.

API requests are case sensitive and should be entered as shown in this manual.

HTTP Methods

Table 1-2 describes the HTTP methods that the Cisco WebEx Social API requests support.

Table 1-2 HTTP Methods 

HTTP Method
Description

DELETE

Deletes a resource.

GET

Retrieves a resource or information about a resource. The information is contained in a message body in the response.

HEAD

Returns a response with an HTTP header only. A message body is not included in the response.

If the response includes a list of resources, Cisco WebEx Social adds the x-quad-count custom header to the response, which provides a count of the resources that are returned.

You can use the HEAD method instead of the GET method with any Cisco WebEx Social API GET operation.

This document explains the HEAD operations that do not accept query parameters.

OPTIONS

Retrieves a list of the HTTP methods that a URI supports.

You can use the OPTIONS with any Cisco WebEx Social API operation URI to see the HTTP methods that the URI supports.

POST

Creates a resource.

PUT

Updates a resource.


Identifiers of Cisco WebEx Social Entities

Some Cisco WebEx Social API operations require you to designate the Cisco WebEx Social entity that you want the operation to affect. For example, to retrieve information about a certain Cisco WebEx Social user, you need to designate that user when you execute the operation. You make such designations by including the identifier of the entity in the URI of the operation request.

To determine a particular identifier, you can execute an API operation that returns it. Table 1-3 describes the identifiers that various Cisco WebEx Social operations use and lists operations that you can execute to determine the identifier that you want.

Table 1-3 Cisco WebEx Social Entity Identifiers 

Identifier
Description
Obtaining

category_id

Identifier of a Cisco WebEx Social community category

Use the operation Get Information about Community Categories.

For example, the response to the following request includes the identifiers of all community categories:

GET http://webexsocialserver/api/quad/rest/ 
communities/categories
 
        

comment_id

Identifier of a comment in a Cisco WebEx Social post

Use the operation Get Information about Comments for a Post. (You also receive a comment identifier when you add a comment to the post.)

For example, the response to the following request includes the identifiers of comments that are associated with the post with the identifier 35:

GET http://webexsocialserver/api/quad/rest/posts/ 
35/comments
 
        

community_id

Identifier of a Cisco WebEx Social community

Use the operation Get Information about Communities to which You Belong, or the operation
Get Information about Communities.

For example, the response to the following request includes the identifiers of communities to which you belong:

GET http://webexsocialserver/api/quad/rest/users/ 
@me/communities
 
        

The response to the following request includes the identifiers of all communities that are visible to you:

GET http://webexsocialserver/api/quad/rest/ 
communities
 
        

consumer_id

Identifier of a Cisco WebEx Social API consumer

Use the operation Get Information about All API Consumers. (You also receive a consumer identifier when you add an API consumer.)

For example, the response to the following request includes the consumer identifier for each API consumer:

GET http://webexsocialserver/api/quad/rest/ 
management/apiconsumers/@all
 
        

document_id

Identifier of a Cisco WebEx Social document file

Use the operation Get Information about a Document Folder.

For example, the response to the following request includes the document identifiers for all document files that are in the document folder with the identifier 1357:

GET http://webexsocialserver/api/quad/rest/ 
documentfolders/1357
 
        

favorite_id

Identifier of a favorite relationship

Use the operation Get Information about a Post, with the meta query parameter equal to favorite.

For example, the response to the following request includes the favorite identifier for the favorite relationship between you and the post with the identifier 455:

GET http://webexsocialserver/api/quad/rest/posts/ 
455?meta=favorite
 
        

file_id

Identifier of a file that is associated with a Cisco WebEx Social post or micropost

The file identifier is returned when you upload a file by using the operation Upload a File.

For example, the response to the following request includes the file identifier for the file that you uploaded:

POST http://webexsocialserver/api/api/quad/rest/ 
files
 
        

folder_id

Identifier of a Cisco WebEx Social document folder

Use the operation Get Information about the Document Library of a User, or the operation
Get Information about the Document Library of a Community. These operations return the identifier of the top level document folders in a document library. You can then use the operation Get Information about a Document Folder as needed to obtain the identifier of the desired document subfolder.

For example, the response to the following request includes the folder identifiers for all document folders in the top level of the document library of the user with the identifier 1234:

GET http://webexsocialserver/api/quad/rest/users/ 
1234/documentlibrary
 
        

The response to the following request includes the folder identifiers for all document folders in the top level of the document library of the community with the identifier 9876:

GET http://webexsocialserver/api/quad/rest/ 
communities/9876/documentlibrary
 
        

The response to the following request includes the folder identifiers for all document subfolders under the document folder with the identifier 1852:

GET http://webexsocialserver/api/quad/rest/ 
documentfolders/1852
 
        

follow_id

Identifier of a follow relationship

Use the operation Get Information about a User, with the meta query parameter equal to follow.

For example, the response to the following request includes the follow identifier for the follow relationship between you and the user with the identifier 22:

GET http://webexsocialserver/api/quad/rest/users/ 
22?meta=follow
 
        

like_id

Identifier of a like relationship

Use the operation Get Information about a Post, with the meta query parameter equal to like.

For example, the response to the following request includes the like identifier for the like relationship between you and the post with the identifier 245:

GET http://webexsocialserver/api/quad/rest/posts/ 
245?meta=like
 
        

membership_
request_id

Identifier of a request for membership in a Cisco WebEx Social community

Use the operation Add Yourself to a Community, or the operation Get Information about Membership Requests for a Community.

For example, the response to the following request includes the identifier of a membership request, if one was generated, for the community with identifier 123:

POST http://webexsocialserver/api/quad/rest/ 
communities/123/users/@me
 
        

The response to the following request includes the identifiers for all membership requests for the community with the identifier 456:

GET http://webexsocialserver/api/quad/rest/ 
communities/456/membershiprequests
 
        

post_id

Identifier of a Cisco WebEx Social post

Use an operation that returns information about posts, such as the operation Get Information about Posts that are Visible on the Profile of a User.

For example, the response to the following request includes the post identifiers for posts that are visible on the profile of the user with the identifier 335:

GET http://quadserver/]/api/quad/rest/users/335/ 
posts/@profile
 
        

user_id

Identifier of a Cisco WebEx Social user

Use the operation Get Information about a User with the Designated E-mail Address or Screen Name.

For example, the response to the following request includes the identifier of the user with the screen name patkim:

GET http://webexsocialserver/api/quad/rest/users 
?filterBy=screenName&filterValue=patkim
 
        

usergroup_id

Identifier of a Cisco WebEx Social user group

If the user group is assigned to a community, use the operation "Get Information about User Groups Assigned to a Community" section.

For example, the response to the following request includes each the identifier for each user group that is a member of the community with the identifier 9876.

GET http://quadserver/api/quad/rest/communities/ 
9876/communityusergroups
 
        

If the user group is not assigned to a community, edit the user group in the Cisco WebEx Social web-based interface and look at the value for userGroupId, which appears at the end of the address in the Address bar of your browser.

version_id

Identifier of the version of a document file

Use the operation Get Information about All Versions of a Document File.

For example, the response to the following request includes each version identifier for the document file with the identifier 1357.

GET http://webexsocialserver/api/quad/rest/ 
documents/1357/versions
 
        

your_user_id

Your Cisco WebEx Social user identifier

Use the operation Get Information about Yourself.

For example, the response to the following request includes your user identifier:

GET http://quadserver]/api/quad/rest/users/@me
 
        

Request Payloads

Request payloads are sent with POST and PUT requests. A payload defines the new resource or the update that is to be made to an existing resource.

Depending on the operation, a payload is provided in XML, JSON, or multipart/form-data format. The payload identifies the resource fields in which information is to be created or updated, and supplies the value for each field.

API Responses

Every API operation generates a response. A response always includes an HTTP header, and may include a response payload. An HTTP header provides general information about the execution of an operation, and may include information requested. A response payload contains one or more resources and related information.

The response that an API operation returns depends on the HTTP method that is used with the response. A GET or POST operation return a response that includes a payload. A DELETE, HEAD, or PUT operations return a response that includes and HTTP header only. A HEAD operation includes a count in the header, if the response includes a list of resources.

When a response payload includes a resource that contains a child resource, the child resource displays only the fields that its @basic resource profile defines. (See the "Resource Profiles" section for descriptions of @basic resource profiles.)

The following sections provide general examples of standard API responses:

Response with HTTP Header Only

Response with Payload

Response with HTTP Header Only

An API response that includes an HTTP header only is returned by DELETE, HEAD, and PUT operations.

Table 1-4 describes some items that can appear in this type of response. Example 1-1 shows an example of this type of response.

Table 1-4 Items in HTTP Header-Only Response 

Item
Explanation

HTTP status code

Shows an HTTP status code, which provides information about the execution of the operation.

For explanations of status codes, see the "HTTP Status Codes" section.

x-quad-count

Provides the count of items, if a count is requested by using a HEAD operation.

Content-Type

Identifies the content type of a response payload. This line is included even though a response payload is not part of the response.

Content-Length

Indicates that no response payload (content) is included.

Date

Indicates the date and time that the response was received.


Example 1-1 HTTP Header-Only Response

HTTP/1.1 200 OK
x-quad-count: 1
Content-Type: application/json
Content-Length: 0
Date: Fri, 07 Oct 2011 18:46:04 GMT

Response with Payload

This section provides examples of API responses that include a response payload. Table 1-5 describes some items that can appear in this type of response (not all items appear in all response types). Example 1-2 shows a response in XML format. Example 1-3 shows a response in JSON format. Example 1-4 shows a response in Atom format.

These examples to not apply to operations that return activities or watch lists.

Table 1-5 Items in Response with Payload 

Item
Explanation

statusCode

Shows an HTTP status code, which provides information about the execution of the operation.

For explanations of status codes, see the "HTTP Status Codes" section.

startIndex

Number that identifies the position in a list of items of the first item to include in the return results.

For related information about pagination, see the "Query Parameters" section.

itemsPerPage

Number of items that appear on the current page. The default value is 25.

For related information about pagination, see the "Query Parameters" section.

totalResults

Total number of results that match the request.

filtered

Indicates that the response is filtered (true) or is not filtered (false).

For information about filtering, see the "Query Parameters" section.

sorted

Indicates that the response is sorted (true) or is not sorted (false).

For information about sorting, see the "Query Parameters" section.

entry

Contains the resource that the operation requested. Also contains metadata, if requested (see the "Query Parameters" section).

There can be multiple "entry" items.

servermessages

Shows a server message, if one is returned. Server messages provide information about error conditions.

For explanations of server messages, see the "Server Messages" section.


Example 1-2 Response with Payload, XML Format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:response 
xmlns:ns2="http://quad.cisco.com/ns/1.0/xml">
  <statusCode>200</statusCode>
  <startIndex>0</startIndex>
  <itemsPerPage>1</itemsPerPage>
  <totalResults>1</totalResults>
  <filtered>false</filtered>
  <sorted>false</sorted>
  <entry>
  </entry>
  <serverMessages>
  </serverMessages>
</ns2:response>

Example 1-3 Response with Payload, JSON Format

JSON Response
{
      "statusCode": 200, 
      "startIndex": 0, 
      "itemsPerPage": 1, 
      "totalResults": 1,
      "filtered": false, 
      "sorted": false, 
      "entry": [
            {
                  "data": {},
                  "meta": {}
           }
      ], 
      "serverMessages": null
}

Example 1-4 Response with Payload, Atom Format

HTTP/1.1 200 OK
x-quad-count: 1
Content-Type: application/atom+xml
<feed xml:base="http://webexsocialserver/api/quad/rest/" xmlns="http://www.w3.org/ 
2005/Atom">
   <title type="text"></title>
   <updated></updated>
<entry>
      <id>2</id>
      <title type="text"></title>
      <summary type="html"/>
      <published></published>
      <updated></updated>
   </entry>
</feed>

HTTP Status Codes

The response to an API request always contains an HTTP header. The HTTP header includes one of the HTTP status codes that Table 1-6 describes.

Table 1-6 HTTP Status Codes 

Code
Meaning
Explanation

200

OK

The operation completed successfully

201

Created

A new resource was created

204

No content

The operation completed successfully but no content is included in the response body

207

Multi-status

The message body that follows is an XML message that might contain other response codes

303

See other

More information is available in the URI that is indicated

400

Bad request

There is an error in the format or content of the request

401

Authorization access required

The client that submitted the request did not provide valid authentication credentials

403

Authorization fail

The client that submitted the request is not authorized to perform the requested action

404

Not found

The resource that the request is targeting does not exist

409

Conflict

The operation did not succeed because a conflict occurred (for example, and edit conflict)

500

Internal server error

The operation did not succeed because of an service error

501

Not implemented

The operation did not succeed because the server that the request designates does not support the functionality that is required to complete the request

503

Service unavailable

The operation did not succeed because the Cisco WebEx Social service is not available


Server Messages

The response to an API request may contain a server message in its response body. Table 1-7 describes the server messages.

Table 1-7 Server Messages 

Code
Meaning
Explanation

QUAD-100

Protocol error

A network protocol error occurred

QUAD-200

Authentication failed

An authentication error occurred in Cisco WebEx Social

QUAD-201

User account error

An error occurred with a Cisco WebEx Social user account

QUAD-300

Unauthorize

An authorization error occurred in Cisco WebEx Social

QUAD-301

Policy error

A Cisco WebEx Social policy prevented an operation from executing

QUAD-302

Role error

A Cisco WebEx Social user role prevented an operation from executing

QUAD-303

Entitlement error

An error occurred with Cisco WebEx Social functionality management

QUAD-400

Client-side error

An error related to the API client occurred

QUAD-401

Request timeout

The server did not respond to an API request

QUAD-402

Bad request

An API request was not formatted properly or another error occurred with the request

QUAD-404

Resource not found

The resource that the request is targeting does not exist

QUAD-500

Internal server error

An internal error occurred on the Cisco WebEx Social server

QUAD-501

Database error

An error occurred with the Cisco WebEx Social database

QUAD-502

No such entity

A Cisco WebEx Social resource was not found

QUAD-503

Timeout

The API operation timed out and did not complete

QUAD-504

Meta processing error

An error processing metadata occurred

QUAD-505

Conflict

A conflict , such as an edit conflict, occurred

QUAD-600

Success

The operation completed successfully


Query Parameters

Many Cisco WebEx Social API operations accept one or more query parameters. The standard query parameters let you designate criteria that data in a response must match, and sort and paginate data that is returned.

Some operations accept additional special query parameters, which are explained in detailed operation descriptions when they apply.

The first query parameter that you include in an API request must be preceded by a question mark (?). When you include multiple query parameters in an API request, separate each parameter with an ampersand (&). Query parameters are case-sensitive.

Table 1-8 describes the standard Cisco WebEx Social API query parameters. Information about how each of these parameters applies to an operation is provided with the detailed description of the operation.

Table 1-8 Standard Query Parameters 

Description
Query Parameter
Examples

Field selection—Causes an API operation to include data only from the designated resource fields in the return results.

You can specify one or more fields, one or more resource profiles (which define fields), or a combination of fields and resource profiles.

fields={[field_1[,...[field_n]]][profile_1
[,...[profile_n]]]}

where:

field_n—Name of a resource field to match. When specifying multiple field names, separate each one with a comma.

profile_n—Name of a resource profile to match. For information about resource profiles, see the "Resource Profiles" section.

The following query parameter returns data from the resource fields description and id:

fields=description,id
 
        

The following query parameter returns data from the resource fields that the "@basic" resource profile defines:

fields=@basic

Filter—Causes an API operation to return only resources that include the designated resource field and field value.

filterBy=field&filterValue=value

where:

field—Name of a resource field to match.

value—Value of the resource field.

The following query parameter returns resources that include "Jones" in the lastName resource field:

filterBy=lastName&filterValue=Jones

Sort—Causes an API operation to present resources that are returned in ascending or descending alphanumeric order on the designated field.

sortOrder={ascending|descending}
&sortBy=field

where:

ascending—Designates that results are presented in ascending alphanumeric order.

descending—Designates that results are presented in descending alphanumeric order.

field—Name of the resource field on which to sort.

The following query parameter presents the return result in ascending alphanumeric order on the id resource field:

sortOrder=ascending&sortBy=id

Index—Designates the first item that an API operation returns .

You can use this parameter to paginate return results by sending multiple API requests and adjusting the first item each time.

Be default, an API operation returns all items in a list.

startIndex=position

where position is a number that identifies the position in a list of items of the first item to include in the return results. The number 0 indicates the first item in a list, 1 indicates the second item, and so on.

The following query parameter returns 25 consecutive items (by default) beginning with the sixth item:

startIndex=5

Count—Designates the maximum number of items that an API operation includes in the return results.

By default, an API operation returns up to the first 25 matching items that follow the item that the startIndex parameter defines, or that follow the first item if startIndex is not used.

count=total_items

where total_items is the number of consecutive items to include in the return results.

The following query parameter returns 10 consecutive items:

count=10

Metadata—Causes an operation to include the relationship metadata that was requested in addition to the resource that is returned.

Metadata includes the identifier of the relationship, and the relationship value from a relationship resource for the logged-in user and the resource that is returned.

This query parameter is supported for requests that return a User, Post or relationship (Favorite, Follow, and Like) resource.

Chapter 16 "Response Examples," includes examples of response payloads that include metadata.

meta={[follow]|[like][,][favorite]}

If a request returns the User resource or a relationship resource with the User resource as its destination field, only follow applies.

If a request returns the Post resource or a relationship resource with the Post resource as its destination field, only like and favorite apply. You can use either or both items in any order. If you use both items, separate them with a comma.

The following query parameter returns the follow ID and follow relationship that correspond to the data that is returned:

meta=follow
 
        

The following query parameter return the like ID, like relationship, favorite ID, and favorite relationship that correspond to the data that is returned:

meta=like,favorite