CHAPTER 1 Cisco Pulse OpenSocial API Overview This overview discusses these topics: • Cisco Pulse OpenSocial API Overview, page 1-1 • Cisco Pulse OpenSocial API Architecture, page 1-2 • Understanding the URL Templates, page 1-3 Cisco Pulse OpenSocial API Overview OpenSocial is comprised of APIs that enable third-party developers to create web-based social network applications. Cisco Pulse fully supports these categories of OpenSocial APIs: • People • Groups • Application data Cisco Pulse extends these APIs with the REST APIs described in Table 1-1. Table 1-1 Cisco Pulse OpenSocial REST API Extensions REST API Extensions Description Authentication APIs Allows the developer to log into the OpenSocial server, thereby requesting a session ID for authentication. Pulse Locator APIs Auto-completion APIs Allows users to view the Pulse Vocabulary terms that match the term they are typing into the Pulse Locator search interface. People search APIs Allows users to search for people with recent experience with a specified term. Profile search Allows the system to search profiles. Document search APIs Allows users to search for relevant documents for a specified term. Video search APIs Allows users to search for relevant videos for a specified term. Cisco Pulse API Reference Guide OL-21500-02 1-1 Chapter 1 Cisco Pulse OpenSocial API Overview Cisco Pulse OpenSocial API Architecture Table 1-1 Cisco Pulse OpenSocial REST API Extensions (continued) REST API Extensions Description Vocabulary management APIs Vocabulary APIs Allows users to add, modify, delete, and get terms in the Pulse and Restricted Vocabularies. User-suggested tag APIs Allows users to suggest tags for inclusion in the Pulse Vocabulary and business administrators to approve or reject the suggestions. Also allows business administrators to get all or specified user-suggested tags and to modify them. Tag APIs Allows users to add a tag to their profiles, change the status of a tag, and get tags. Profile APIs Allows users to add information to their profiles, modify their profile information. Allows a system administrator to delete profiles. As shown in Figure 1-1, the REST APIs allow a developer to integrate the back-end services of Cisco Pulse with interfaces customized for your organization. Figure 1-1 Cisco Pulse OpenSocial REST APIs REST API request Third-party Cisco Pulse server back-end server REST API response 277558 Cisco Pulse also supports OpenSocial JavaScript API extensions, which allow an OpenSocial gadget to directly invoke Cisco Pulse’s OpenSocial services through JavaScript objects and functions and without explicitly using the Cisco Pulse OpenSocial REST API extensions. For more information, see Chapter 7, “Cisco Pulse OpenSocial JavaScript API Overview.” Cisco Pulse OpenSocial API Architecture The Cisco Pulse OpenSocial API architecture is comprised of these major elements, which are shown in Figure 1-2: • OpenSocial container • REST APIs for people, groups, application data, and activities • OpenSocial API extensions, which are Cisco Pulse-specific REST APIs to retrieve raw data • OpenSocial JavaScript API extensions, which sends requests to get, create, update, and delete Cisco Pulse data that resides on the server. Cisco Pulse API Reference Guide 1-2 OL-21500-02 Chapter 1 Cisco Pulse OpenSocial API Overview Understanding the URL Templates Figure 1-2 Cisco Pulse OpenSocial API Architecture UI Widget UI Widget UI Widget (Cisco Specific) (Cisco Specific) (Customer Specific) JavaScript APIs High-level Pure OpenSocial REST APIs Low-level OpenSocial Java APIs OpenSocial Container REST (OS) to SQL to translation layer SQL Query Layer Groups LDAP MT (Manual Tags) CI Information Information Statistics Information Information 277559 Understanding the URL Templates For each Cisco Pulse OpenSocial REST API, a URL template is provided. For example: http://hostname:7090/social/rest/pulseservices/username/svcId?privilege=privilege&vocabType= vocabType&mainTerm=mainTerm&syn1=syn1&syn2=syn2&syn3=syn3&syn4=syn4&syn5=syn5 In the URL template, the question mark (?) acts as a delimiter. The parameters to the left and right of the question mark have these characteristics: • Parameters to the left of the question mark specify the location of the API. Therefore, the order of these parameters is critical. If you change the order of these parameters, your request fails. The hostname, username, and svcId parameters are present in most of the URL templates. Table 1-2 describes these parameters. • Parameters to the right of the question mark are the Cisco Pulse extensions. The order of these parameters is not critical. You can specify these parameters in any order. A parameter table, which is provided for each API, supplies the expected or optional values for each parameter. Cisco Pulse API Reference Guide OL-21500-02 1-3 Chapter 1 Cisco Pulse OpenSocial API Overview Understanding the URL Templates Table 1-2 General URL Template Parameters Parameter Description Expected Value Status hostname Specifies the name of the host on hostname Required which the OpenSocial server resides. For example, myhost1. This host is the Pulse Connect Appliance. The hostname can also be the IP address of the appliance. username Specifies a Cisco Pulse username, Cisco-Pulse [email protected] Required which you must specify in an email For example, george@ address format. mycompany.com svcId Specifies the ID of the service you are A parameter table, which is provided Required invoking. for each API, supplies the service ID that you must specify for the API. The convention of italics denotes arguments or variables, which must be filled in with a specified value. Note For the sake of brevity, the general parameters in Table 1-2 and authentication-related parameters, which are described in “Login Request” section on page 2-3, are not described with the URL template for each API. Cisco Pulse API Reference Guide 1-4 OL-21500-02.