In Chapter 5, we explained how to use Yammer Open Graph API to bring information stored in different business applications into Yammer and allow users to discover data from other applications and see the full view in a structured manner. This is all good, but it provides only one-way integration—from your business applications to Yammer. What if you want to integrate Yammer data into your business applications and make your applications more social and able to share content? The Yammer REST APIs provide this capability.

In this chapter, we will explain Yammer REST APIs, which allow developers to access Yammer data from line-of-business applications running on different platforms. Yammer’s REST APIs allow inbound and outbound flow of messages. This chapter covers:

• Explanation of REST
• Introduction to Yammer’s REST APIs
• Yammer features that can be accessed using REST APIs from line-of-business applications
• Yammer’s REST service endpoints details
• Lab exercise using the SPDS University application to see how to access data from Yammer and write data into Yammer using Yammer’s REST API endpoints

REST

As per Wikipedia, “Representational State Transfer (REST) is a software architecture style consisting of guidelines and best practices for creating scalable web services”.

REST relies on stateless, client-server, cacheable HTTP channel and is a lightweight alternative to using web services or RPC. RESTs benefits include:

• It’s platform independent
• It’s programming-language independent
• Can be used when firewalls exist
• REST services use HTTP as main communication channel and have a uniform interface where resources are identified as URIs. This allows easy implementation of REST endpoints.

Any service based on the REST protocol is called a RESTful service. In a RESTful application, REST-enabled resources are maintained in an accessible data store. When a request is sent to a RESTful application to perform an action (create, retrieve, delete, or update), the RESTful application performs the operation and provides a response, as shown in Figure 6-1. All RESTful applications use HTTP requests to post and get data.

As all REST API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the distributed infrastructure. For more information about REST, you may find the following third-party references useful:

• Wikipedia (http://en.wikipedia.org/wiki/REST) provides a good overview of REST
• HTTP 1.1 method definitions (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html); includes a specification for GET, POST, PUT, and DELETE

Yammer REST APIs

Like other social networking applications Yammer has provided REST APIs to develop custom integrations with business applications. Yammer REST APIs are most common way to integrate your line-of-business applications with Yammer and enables you to add social features to virtually any type of business application within your organization.

Yammer REST API is the lowest-level API provided by Yammer and enables developers to build both client and server applications. In this chapter, we will go through all the available Yammer REST endpoints and try to explain them in a manner that will allow you to implement integrations with your business applications. First, let’s look at the main features of Yammer APIs.

Yammer REST API Features

Before you develop integrations with Yammer REST APIs, it’s useful to know about various features provided by them. Here are the main features of using Yammer REST APIs:

• The REST API is available for any platform that can make HTTP calls over SSL. Current supported platforms are Ruby, Python, JavaScript, iOS, .NET, and Windows Phone.
• Yammer APIs mainly support JSON (JavaScript Object Notation), but it also supports XML format for many APIs.
• Developers simply need to create HTTP requests going to Yammer and process the JSON returned from Yammer in response on their business applications.
• Using Yammer REST APIs, you can work on different Yammer objects, including messages, users, groups, and so on.
• Yammer REST APIs enable developers to access Yammer’s data using simple HTTP methods like GET and POST.

What You Can Do with Yammer REST APIs

As mentioned, Yammer REST APIs help you develop and add social features to your business application, and you can easily post messages or activity updates from any platform. Here are some useful examples of what you can do.

• Bring Yammer’s social experience to your business applications.
  • You can use REST APIs to view, create, edit, or delete messages on Yammer.
  • You can use Yammer REST APIs to append or delete attachments or topics to messages or message threads.
  • You can provide and manage subscriptions to Yammer topics, discussion threads, and users from business applications.
  • You can use Yammer REST APIs to view organizational charts and relationships.
  • You can add or remove relationship between users.
  • You can send email invites to users who have not joined Yammer using REST APIs.
• Search Yammer content from other applications.
  • Using Yammer REST APIs, you can search for Yammer data directly from your business applications.
  • You can use the Yammer autocomplete feature in your business applications.
• Meet compliance needs.
  • Yammer also provides a data export API, which can help IT administrators archive Yammer Network content and be compliant with an organization’s rules and legal requirements.
• Monitor Yammer usage.
  • You can use data export to do reporting on Yammer content, provide useful insight on adoption, and help measure ROI from the Yammer investment.

Before You Start Using the Yammer REST APIs

Before you start using the Yammer REST endpoints, it is important to familiarize yourself with the high-level requirements.

• Authentication on Yammer
• User privileges

Let’s explore why these are required.

Authentication on Yammer

Just like any enterprise application, before requesting Yammer data, any request to access Yammer data must be authorized by the authenticated user. This authorization is done using the Yammer Authentication model based on the OAuth2.0 protocol, which we covered in detail in Chapter 4. As you know when you do user authentication, Yammer provides an access token that’s linked to the authorized user. Developers should send an authorization header with the access token to make sure the request to POST/GET/DELETE using the Yammer REST API is authenticated by Yammer.

The format of the authentication header is:

Authorization: Bearer [Access Token]

Any operation that modifies the Yammer data can be performed only by the user who owns that data. It’s important to understand that the user's access token much be strongly protected when used with REST APIs. If a security breach occurs, an attacker can post and read messages to/from Yammer. So, you need to use measures like encryption, permission, and least privilege policy to protect the user authorization access tokens in your business applications.

User Privileges

Your enterprise Yammer network has three types of users and each user type has a different set of permissions on Yammer. As a developer, you should consider which accounts are used while doing integration using Yammer REST APIs.

The different user types are described in Table 6-1.

Getting Started with Yammer REST APIs

Yammer REST APIs are useful wrappers that speed up the development of your applications. There are different Yammer REST APIs for different Yammer objects:

• Messages
• Users
• Groups
• Relationships
• Notifications
• Suggestions
• Subscriptions
• Autocomplete
• Search
• Networks

Yammer API Operations

Table 6-2 provide the available HTTP methods that can be used for invoking Yammer resources.

The operations that are supported for the different types of resources are summarized in Table 6-3.

There are few other considerations you should know about when implementing Yammer REST APIs in your applications:

• Admin actions: When you plan to use administrative Yammer API for actions like adding or deleting Yammer users, you should only use authorization access tokens from a Yammer-verified admin user.
• Versioning: The Yammer API version is visible in the URL of the REST API endpoints. For example, /api/v1. As per the Yammer guidelines, there could be additional elements added to output from endpoints. When elements are added or removed a new version of the API is typically released.
• Calling styles: There are several ways to invoke the API from your business applications.
  • Using a REST endpoint directly
  • Using a REST endpoint from JavaScript (no server-side code required)
  • Using a server-side application (explained later in the SPDS University application exercise)
  • Using REST endpoints directly. You need to specify Yammer actions using the HTTP verbs POST, GET, PUT, or DELETE. The Yammer resource is specified by a unique URI:

    https://www.yammer.com/api/v1/users.json

• REST from JavaScript: Developers can invoke the Yammer REST API from JavaScript using the callback query parameter and a callback function. This allows developers to write rich applications without need to write server-side code:

  function PostYammerMessage(val) {
     var msg = document.getElementById('msgtxt').value;
     var groupID = "71618329";
      if(msg == ""){
       alert ("Message cannot be empty!");
       return false;
      }
   yam.platform.request(
     {
      url: "https://api.yammer.com/api/v1/messages.json"
      , method: "POST"
      , data: {
       "body" : msg,
       "group_id" : groupID
      }
      , success: function (msg) { alert("Yammer message Post was Successful!"); }
      , error: function (msg) { alert("Yammer Post failed"); }
      }
      )
   }

In the previous code, the PostYammerMessage() function accepts a message and then posts the request to Yammer’s messages REST endpoint to a Yammer group.

Later in this chapter, we will explain the use of REST endpoints using an example. But before that, you need to understand the basics of the different Yammer REST endpoints.

REST Endpoints

Let’s go through all the available endpoints and explore how to use them in your application.

Messages

All posted Yammer messages are displayed as feeds and messages are grouped into threaded conversations, as shown in Figure 6-2. Using Yammer REST APIs, you can post a message to Yammer, reply to a post, follow a post, share a post, delete a post, email a Yammer message, and do many other operations.

Yammer has provided many APIs to view and retrieve messages. Yammer’s feed is the information hub, and it provides three feed views that users can toggle among, as highlighted in Figure 6-3.

As shown in Figure 6-3, the three view options are Top, All, and Following. The Top view shows the conversations most relevant to user, based on what that user subscribes to and her interactions with the Yammer network content. The All view renders all the conversations to which that Yammer user has access within his Yammer network, and the Following view displays messages that users actively subscribe to. This includes conversations that the user’s followers have participated in or liked, conversations that have been tagged with a Yammer topic that users follow, and conversations that have been posted in one of the user’s Yammer groups.

Retrieve All Public Messages

You use the message.json REST API endpoint to get all the public messages and conversations in the user’s Yammer network. This is linked to the All view in the Yammer web interface.

Endpoint:

https://www.yammer.com/api/v1/messages.json

Or:

https://www.yammer.com/api/v1/messages.xml

Table 6-4 lists the required parameters.

Later in this chapter, you will go through a detailed exercise on how to retrieve messages from Yammer using the SPDS University business application case study.

Other Message REST APIs Used to GET Yammer Messages

Table 6-5 lists the related RESTful APIs used to GET messages from different feeds on Yammer, such as my_feed.json, which is the user’s feed, algo.json, which is the algorithmic feed, and following.json, which is the feed the resource users are following.

All the previously mentioned endpoints use the same parameters as mentioned in Table 6-4.

Manipulating/Updating Messages REST API

Yammer’s REST APIs provide a simple way to post messages to Yammer. You can use the same APIs to post your message to the whole company, broadcast to everyone in the network, post to a specific group, send a private message, add topics, and so on.

In order to post messages to Yammer, you need different IDs like a Group ID, User ID, Message ID, and Feed ID. You can use the GET method of message.json to retrieve the IDs of different objects. Tables 6-6 and 6-7 list the endpoints and their related parameters.

Here’s an example:

function postAMessage() {
    var testMessage = { "body": "Hello Test, have you seen this" + location.href };
    yam.platform.request({
        url: "messages.json",
        method: "POST",
        data: testMessage,
        success: function (msg) {
            console.log("Message Posted Successfully");
        },
        error: function (msg) {
            console.log("Message Posting Error: " + msg.statusText);
        }
    });
}

Other parameters for the POST message Open Graph (OG) object parameter include:

• og_<property>: This parameter is required if your message contains an Open Graph (OG) object as an attachment.
• og_fetch (true/false): If this parameter is set to true, Yammer will get all the available Open Graph parameters for a specified page URL.

If you want to delete a message that contains an OG object, you need to specify the og_url parameter. Along with this there are other optional parameters specified in Table 6-8. Refer to the Open Graph site for the latest details (http://ogp.me/).

Delete a Posted Message from Your Business Application

You can remove a message from your application using Yammer. Table 6-9 provides the endpoint details.

Adding an Attachment to a Message

You can easily add an attachment file to a message from your application. Again, the Yammer message must be related to the current user.

Emailing Messages to Yammer

Using Yammer REST API, you can programmatically send a copy of any message in Yammer as email to a currently logged in user. Figure 6-4 shows how the message will appear in email.

Table 6-11 provides the endpoints and the parameters for emailing a message.

Example:

https://www.yammer.com/api/v1/messages/email?message_id=436054827

Viewing a Thread

This endpoint (Table 6-12) is used to get the Yammer conversation thread of a message.

Examples:

https://www.yammer.com/api/v1/threads/436054827.json

https://www.yammer.com/api/v1/threads/436054827.xml.

Figure 6-5 shows how the XML looks in Yammer conversation thread output. You can see that the output type is thread and determine which group it is related to.

Liking a Message

Yammer provides many different uses of the Like button; for example, people can use the Like button when they prefer a post and feel it is informative.

Yammer provides REST APIs (Table 6-13) to programmatically mark a message as Liked by the current user. Chapter 7 provides a step-by-step guide on how to implement this feature in your line-of-business applications.

You can also use the Yammer Like button as shown in Chapter 2 with the Yammer Embed functionality.

Example:

https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=436054827

Unlike a Message

Yammer provides REST APIs (Table 6-14) to programmatically unmark a message liked by current users. Chapter 7 provides a step-by-step guide on how to implement this feature in your line-of-business applications. The implementation remains the same as you saw in previous examples. The only difference is the method type. Instead of using POST, you use DELETE.

Example:

https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id= 436054827

Yammer Topics

Yammer Topics provides a better way to organize your messages around specific subjects. The user who is posting or editing a message can add topics it and this will allow users to view all the messages posted using the same topics. Users can follow topics. Once a user follows a topic, any posts that contain the topic name will appear in the user’s MyFeed.

If you want to show the trending topics or get all the Yammer posts by topic, the following Yammer REST endpoints (Table 6-15) can be useful.

Yammer Users

In Yammer, users are the key player of any social platform. Performing user management in Yammer through your line-of-business applications is as important as managing users of your sites. You can view all the users in the network and see their profiles, who they following, and so on, using the Yammer web interface (Figure 6-6).

Yammer has provided a REST endpoint to work on the user object in different manners:

• Get all users on a given network for your internal analysis or audit.
• Engage users on an internal application by showing their Yammer profile info on business applications.
• Make applications more social by adding details of messages liked by users, topics specified by users, and group membership of users.
• Update information about users from business applications.
• Suspend or delete a user.
• Delete messages directly from business applications behalf of a user.
• Search users on Yammer by email address and share their Yammer profiles in business applications.
• Show relationships between users and show the org chart of the current user in business applications.

Table 6-16 lists the APIs available from Yammer related to user objects.

The best way to view data about a particular user in XML or JSON is to use the browser window and retrieve the user’s data. You can get the user ID from previous examples and form the URL as https://www.yammer.com/api/v1/users/current.xml or https://www.yammer.com/api/v1/users/current.json.

Type the URL in the browser to retrieve the XML, as shown in Listing 6-1 for user ID 1510462475. You will notice when you get the details of the user that you get full profile information, number of followers, number of people followed by the user, the user type, user permissions, different feeds of the user (home, company, and all), number of messages liked by the user, sites bookmarked by the user, and other related details.

<response>
<type>user</type>
<id>1541217186</id>
<network-id>2022718</network-id>
<state>active</state>
<guid nil="true"/>
<job-title>Marketing Assistant</job-title>
<location>U.S.</location>
<significant-other>Janet</significant-other>
<kids-names>Charlie, Donna</kids-names>
<interests>
Running, Yoga, Cooking, Creative Writing, Digital Cameras
</interests>
<summary>
I have been at SDPS for five years as a Marketing assistant. I like to help marketing teams in effective campaigns.
</summary>
<expertise>
Marketing Communication, Creative Writing, Product Vision, Consumer Advocate, Market Analysis
</expertise>
<full-name>Alex Darrow</full-name>
<activated-at>2015-04-23T18:05:54Z</activated-at>
<show-ask-for-photo>false</show-ask-for-photo>
<first-name>Alex</first-name>
<last-name>Darrow</last-name>
<network-name>spdsuniversity.onmicrosoft.com</network-name>
<network-domains>
<network-domain>spdsuniversity.onmicrosoft.com</network-domain>
</network-domains>
<url>https://www.yammer.com/api/v1/users/1541217186</url>
<web-url>
https://www.yammer.com/spdsuniversity.onmicrosoft.com/users/alexd
</web-url>
<name>alexd</name>
<mugshot-url>
https://mug0.assets-yammer.com/mugshot/images/48x48/tFGfQ6ktQDj9szvM2mjpTdgZ2XGRCMJQ
</mugshot-url>
<mugshot-url-template>
https://mug0.assets-yammer.com/mugshot/images/{width}x{height}/tFGfQ6ktQDj9szvM2mjpTdgZ2XGRCMJQ
</mugshot-url-template>
<birth-date/>
<timezone>Pacific Time (US & Canada)</timezone>
<external-urls/>
<admin>false</admin>
<verified-admin>false</verified-admin>
<can-broadcast>false</can-broadcast>
<department>Sales and Marketing</department>
<email>[email protected]</email>
<can-create-new-network>true</can-create-new-network>
<can-browse-external-networks>true</can-browse-external-networks>
<previous-companies>
<previous-company>
<employer>SPDS</employer>
<position>Product Manager</position>
<description>Responsible for new product design</description>
<start-year>2010</start-year>
<end-year>2012</end-year>
</previous-company>
</previous-companies>
<schools>
<school>
<school>Univeristy of Maine, Penn State University</school>
<degree>BSc, MA, Business Communication</degree>
<description>
Course requirements and Online Media Communications electives
</description>
<start-year>2004</start-year>
<end-year>2008</end-year>
</school>
</schools>
<contact>
<im>
<provider/>
<username/>
</im>
<phone-numbers>
<phone-number>
<type>work</type>
<number>+1 858 555 0110</number>
</phone-number>
<phone-number>
<type>mobile</type>
<number>+1 858 555 0109</number>
</phone-number>
</phone-numbers>
<email-addresses>
<email-address>
<type>primary</type>
<address>[email protected]</address>
</email-address>
</email-addresses>
<has-fake-email>false</has-fake-email>
</contact>
<stats>
<following>5</following>
<followers>3</followers>
<updates>0</updates>
</stats>
<settings>
<xdr-proxy/>
</settings>
<web-preferences>
<absolute-timestamps>false</absolute-timestamps>
<threaded-mode>true</threaded-mode>
<network-settings>
<message-prompt>What are you working on?</message-prompt>
<allow-attachments>true</allow-attachments>
<show-communities-directory>true</show-communities-directory>
<allow-notes>true</allow-notes>
<allow-yammer-apps>true</allow-yammer-apps>
<enable-groups>true</enable-groups>
<admin-can-delete-messages>false</admin-can-delete-messages>
<allow-inline-document-view>true</allow-inline-document-view>
<allow-inline-video>true</allow-inline-video>
<enable-private-messages>true</enable-private-messages>
<allow-external-sharing>true</allow-external-sharing>
<enable-chat>true</enable-chat>
</network-settings>
<enter-does-not-submit-message>true</enter-does-not-submit-message>
<preferred-my-feed>algo</preferred-my-feed>
<prescribed-my-feed>algo</prescribed-my-feed>
<sticky-my-feed>false</sticky-my-feed>
<enable-chat>true</enable-chat>
<dismissed-feed-tooltip>false</dismissed-feed-tooltip>
<dismissed-group-tooltip>false</dismissed-group-tooltip>
<dismissed-profile-prompt>false</dismissed-profile-prompt>
<dismissed-invite-tooltip>false</dismissed-invite-tooltip>
<dismissed-apps-tooltip>false</dismissed-apps-tooltip>
<dismissed-invite-tooltip-at nil="true"/>
<dismissed-browser-lifecycle-banner nil="true"/>
<make-yammer-homepage>true</make-yammer-homepage>
<locale>en-US</locale>
<yammer-now-app-id>42686</yammer-now-app-id>
<has-yammer-now>false</has-yammer-now>
<has-mobile-client>false</has-mobile-client>
</web-preferences>
<follow-general-messages>false</follow-general-messages>
</response>

Figure 6-7 shows the sample JSON output of the current user using the REST APIs.

Retrieve All Users

You can use Yammer’s REST API endpoints (Table 6-17) to retrieve all users in a Yammer network. These endpoints support parameters for paging, sort_by, and so on, as listed in Table 6-18.

You can specify the query string parameters listed in Table 6-18.

Create a User

You can create a user using the REST endpoints in Table 6-19.

Additional parameters are supported for creating or updating users:

email (required for creating a new user), full_name, job_title, department_name, location, im_provider, im_username, work_telephone, work_extension, mobile_telephone, external_profiles, ignificant_other, kids_names, interests, summary, expertise, education[] (school,degree,description,start_year,end_year) - accepts multiple attributes i.e. education[]=UCLA,BS,Economics,1998,2002&education[]=USC,MBA,Finance,2002,2004, previous_companies[] (company,position,description,start_year,end_year) - accepts multiple attributes i.e. previous_companies[]=Geni.com,Engineer,2005,2008

Groups REST APIs

As you know, Yammer uses the concept of groups. Groups are a great way to reach a specific audience in your network, such as a specific department in your company like HR or IT. Yammer groups can be private or public. Figure 6-8 shows how Yammer messages, users, and groups are linked.

Yammer REST APIs (Table 6-20) allow developers to integration these groups by joining a new group or leaving existing groups.

Relationships

Microsoft introduced the org chart in the My Profile section of SharePoint 2010. It’s a very nice feature that provides a visual org chart. Yammer provides a very similar org chart, as shown in Figure 6-9.

By using REST APIs, developers can manipulate the org chart.

Use the REST endpoints listed in Table 6-21 to view or manipulate the Yammer org chart.

To delete existing relationships from the user organization chart, use the endpoints listed in Table 6-22.

Yammer Notifications

Yammer Notifications (Figure 6-10) are a quick way to let people know when some actions are being performed related to them. Yammer notifies users of each interaction the users are a part of on the Yammer network via notification bar, email, SMS, or IM.

Yammer REST APIs provide an easy way to retrieve notifications for a particular user so that user can take immediate required actions or reciprocate.

Table 6-23 shows the endpoint for getting the notifications feed for the currently logged-in user.

Yammer Suggestions

Yammer suggests users join similar group (Suggested Groups) or follow similar people (Suggested People) in the same network. This helps users expand their social circles. Figure 6-11 shows the suggestion process on a Yammer web interface.

Similarly, developers can use the available REST API endpoints to provide suggestions to users based on certain application types that they work on regularly (Table 6-24). This allows users to find relevant messages more quickly and collaborate with teams and share information.

Subscription REST APIs

When you follow or subscribe to other users in your network, all the Yammer messages will also appear in your Yammer feed. Let’s consider an example—you are working on a project and you follow other project members who are also on Yammer network. Each time a new post is submitted by other users, all these posts appear in your feeds, providing you with an easy way to get insight. Yammer REST APIs provide an endpoint to retrieve subscriptions (Table 6-25) or manage the subscriptions by following or unfollowing actions of the POST method.

AutoComplete

Autocomplete suggests to the users prepopulated values as the users type in the word. As you start typing the name of a user or group in Yammer, it will try to autocomplete your entry. It will show you similar usernames or group names in drop-down list.

Autocomplete is a useful feature when users are composing a new Yammer message from their application and want to add a group, user, or topic. As soon as you start typing the name of user/group/topic, Yammer starts giving you suggestions based on its existing values.

For example, if the user is typing a new message to all the trainers in a company from an internal training application and want to recognize a trainer on new training calendar, they can start typing “Hello @Al”. When the user pauses, they are prompted with the username Alex to complete what they are typing. Table 6-27 lists the REST endpoints related to autocomplete.

Method: GET

Endpoint: https://yammer.com/api/v1/autocomplete/ranked

We will show you how to use autocomplete with REST API endpoints in the exercise later in this chapter.

Invitations REST APIs

The invitations REST APIs (Table 6-28) give developers the ability to send email to users who have not joined the Yammer network programmatically. The Yammer admin can invite people outside your organization, but if the person (who inviting users) is not the Yammer admin, only the official company domain’s email addresses will be allowed.

Search REST APIs

Yammer’s another cool feature is search, which allows developers to use REST API to search users, groups, and messages that match the search string programmatically.

The search endpoint (Table 6-29) returns a list of messages, users, topics, and groups that match the user’s search query.

The return JSON contains the following objects

• Messages
• Groups
• Topics
• Uploaded files
• Pages
• Praises

Later in the training web application exercise, you will see how to include search results from Yammer using the REST APIs.

Yammer Networks

Yammer provides two types of networks—the internal network and external network (Figure 6-12). An internal network, also known as a home network, is private to an organization and only for its internal employees.

An external network is a separate extension of your home network where organizations can invite users from outside their organization, such as partners, vendors, and so on. While external networks can accommodate users with different email domains, access is invite-only based on users invited by the home network.

The network endpoint (Table 6-30) allows users to select different Yammer networks. The network permalink in indicated in the URL https://www.yammer.com/network_permalink/resource_path.

There are different OAuth tokens when you make REST API requests from your application for each user per network.

Return JSON contains the following properties:

For an example, follow these steps:

1. Open a browser windows and log in to Yammer.
2. Open another tab in the same browser window and type https://www.yammer.com/api/v1/networks/current.json.

The REST API request will return the following JSON detailing lists of Yammer networks of which the current user is a member.

Return value:

{"type":"network","id":54605,"name":"Yammer Developers Network","community":true,"permalink":"yammerdevelopersnetwork","web_url":"https://www.yammer.com/yammerdevelopersnetwork","show_upgrade_banner":false,"header_background_color":"#F7CC65","header_text_color":"#000000","navigation_background_color":"#292929","navigation_text_color":"#FFFFFF","paid":true,"moderated":true,"is_org_chart_enabled":false,"is_group_enabled":true,"is_chat_enabled":true,"is_translation_enabled":true,"created_at":"2009/07/02 22:33:32 +0000","profile_fields_config":{"enable_job_title":true,"enable_work_phone":false,"enable_mobile_phone":false},"unseen_message_count":1,"preferred_unseen_message_count":1,"private_unseen_thread_count":0,"inbox_unseen_thread_count":0,"is_primary":false,"unseen_notification_count":1}]

This covers the main Yammer REST API endpoints. You can refer to these endpoints based on your integration requirements. There are few additional APIs we will talk in this chapter, but first let’s look at how to view Yammer’s REST endpoint output.

Yammer Output in a JSON/XML Viewer

As mentioned, the output of the REST API comes in two formats—JSON and XML. You can retrieve the output of the REST API using the browser. While working with JSON, you may need a JSON viewer.

First we will retrieve the JSON by using the REST APIs. To do this, open Internet Explorer or any other browser (see Figure 6-13).

Type this URL in the address bar: https://www.yammer.com/api/v1/messages.json.

You will be prompted with the screen shown in Figure 6-14.

If you use Chrome, the JSON will be rendered in the browser window, which you can copy directly. You can save the JSON on your local system or open the JSON in a tool like Notepad.

The next step is to use the online JSON viewer. There are many JSON viewers available. The one used in this book is jsonviewer.stack.hu. Open a browser and type in the URL: http://jsonviewer.stack.hu/.

You will be presented with the screen shown in Figure 6-15.

Now click on the Text tab and copy and paste the JSON you retrieved in previous step. Alternatively, you can use the Load JSON Data button to supply an URL and the viewer will load the JSON from that resource.

After pasting in the JSON, click on the Viewer tab (Figure 6-16). You will be presented with the screen shown in Figure 6-17. Clicking on Viewer changes the mode of the viewer. You can expand or collapse the JSON tree on the left side to view the name and the values on the right side.

In order to view the output in the XML, change the REST APIs endpoint URL by changing the .JSON to .XML. For example, from https://www.yammer.com/api/v1/messages.xml (Figure 6-17), type the XML URL in the browser window. The browser will render the output XML file shown in Figure 6-18.

The previous methods to view output from REST endpoints are helpful for debugging and validating purposes when developing integrations.

Now, let’s look at additional REST endpoints provided by Yammer for administration and analysis purposes.

Data Export

The Yammer REST API for data export contains the raw data you would use to perform social mining on the enterprise.

Developers and Yammer administrators can use the available reporting tools to use data exports from Yammer to get reporting models for data visualizations. Developers can use Microsoft Excel and Power BI to get these detailed reports. This helps your organization start analyzing the information contained in Yammer, identify key trends/insights, and use those trends/insights to become a more responsive organization.

Yammer exports include the following list of elements:

• Admins
• Files
• Groups
• Messages
• Networks
• Pages
• Topics
• Users

Using Data Export APIs, you can automate the process of getting regular reports. The data export is a .ZIP file that includes messages, users, topics, and groups that are exported in separate .CSV files. This contains complete details of each data type, such as message ID, timestamps, participants, group names, topic IDs, user IDs, usernames, and so on.

The Files and Notes folders will be exported in folders that are separated from your Yammer network. Notes will be exported in the .HTML format. Note that data exports will only return Files and Notes created or modified during the time mentioned in the data export request.

Yammer (https://developer.yammer.com/v1.0/docs/data-export-api) has provided good guidance on Yammer Data Export using the Yammer Data Export API and a script for your Yammer network admin

Method: GET

Endpoint: https://www.yammer.com/apa/v1/export

Yammer REST APIs Rate Limits

When you develop business applications integrations that use Yammer REST APIs, you may run into a situation where you are notified that you have been rate limited. This means the business application has tried to get information from Yammer too many times. Yammer limits the number of times you can call REST APIs in a given timeframe. When this limit is exceeded, Yammer returns the status code 429(Too Many Requests). So when you’re designing the integrations with Yammer, you have to consider these rate limits.

Yammer enforces the rate limit per user, per Yammer app. Table 6-31 lists the different rate limits.

All rate limits are independent of each other. For example, your application can make 10 messages and 10 notifications separately in the same 30 seconds.

There are certain guidelines that you need to adhere to make sure your application is not blocked due to rate limits.

• Do not exceed one poll per minute when polling for messages using the Yammer REST APIs.
• Try to limit the frequency of checking new messages from your application. This impacts the message’s latency.
• As autocomplete objects are designed to provide instant response for a user as they start typing the text, the Yammer REST APIs allow more frequent polling.

Now that you understand the concepts and details of the Yammer REST APIs, it is important that you can implement them properly. The following exercise will help you adopt Yammer REST APIs in your real world integration scenarios. In the next section, we will cover an exercise on implementing the Yammer REST endpoints.

Yammer REST Endpoint in Practice

Summary

Yammer REST API are one of the easiest and most comprehensive ways to do integrations with business applications. As a developer, you need to understand the architecture of Yammer REST API endpoints and the important requirements to start using Yammer REST services endpoints. You should also follow the best practices and rate limits when using Yammer REST APIs for creating objects in Yammer. In the following chapter, we will cover the different Yammer SDKs and use them to integrate with HTML-based business applications.