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

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

•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

•API Consumer resource operations—Operations for managing Cisco WebEx Social API consumers

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 Appears 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
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
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 Appears 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.

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. Not all operations support filtering. If an operation does support filtering, information about how this parameter applies to that operation is provided with the detailed description of the operation.	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. Not all operations support sorting. If an operation does support sorting, information about how this parameter applies to that operation is provided with the detailed description of the operation.	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. Not all operations support indexing. Information about how this parameter applies to an operation is provided with the detailed description of the operation. 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. Not all operations support counting. Information about how this parameter applies to an operation is provided with the detailed description of the operation. 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 13 "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