Tutorial: Exploring the Yahoo Social APIs

This tutorial introduces basic features of the Yahoo Social APIs using an API Explorer. The API explorer allows you to make HTTP GET calls to URI endpoints and view returned responses in both XML and JSON formats. The API Explorer also includes pop-ups for important concepts and reference documentation.

  1. Starting the Yahoo Social API Explorer

    In your browser, open the Yahoo Social API Explorer. If you have installed the API explorer on your server, open it in your browser.

    The Yahoo Social APIs consist of the following five APIs: Profiles, Connections, Contacts, Status, and Updates. The API Explorer organizes the APIs into columns, with each column having links to different endpoints of the API.

  2. Learning About the APIs

    From the top of each API column, mouse over the labels Profiles API, Connections API, Contacts API, Status API, and Updates API to see pop-ups describing the data returned by each API.

  3. Learning About the GUID

    What's a GUID? From the API Explorer, mouse over the GUID label for the answer. The GUID identifies Yahoo users and is part of nearly every URI of the Yahoo Social APIs. For a detailed explanation, see Globally Unique Identifier (GUID).

  4. Getting Your GUID

    From the Profiles API column, click "Introspective GUID". Your GUID is returned in the value element of the XML response. Your GUID is also shown next to the label GUID. In URI syntax examples, the GUID will be notated as {guid}.

  5. Getting Your Profile

    From the Profiles API column, click "Profile" to get the complete user profile. Examine the XML or JSON response bodies for the type of information available. The Tinyusercard, IDCard, and Usercard are subsets of the Profile. The Tinyusercard contains the most basic profile information.

  6. Getting Your Connections

    From the Connections API column, click "Connections". Notice that the returned response has many repeated connection elements. The endpoint used for getting connections is a collection resource URI, so multiple connections (repeated elements) are returned in the response.

  7. Comparing Collection and Singleton Resources

    Click the tab Individual Connections and read about the differences between collection and singleton resources. Notice the differences in the URI syntax for singleton and collection resources.

    The singleton resource URI includes the GUID ({guid2}) of one connection from the profile owner's ({guid1}) connection list.


  8. Getting One Connection

    From the Individual Connections tab, click one of the singleton resource URIs. Notice that the returned response body only contains one connection element and the URI syntax is different from the collection resource URI.

  9. Paging Collections

    From the Connections API column, click "Connections: pagination" to request the first 5 connections of a collection.

    To page results returned by the Yahoo Social APIs, you append the matrix parameters start and count to a collection resource URI. The value assigned to start is the starting index, and the value assigned to count is the number of items to return.

    Note that the matrix parameters start and count are preceded and joined by a semicolon as seen here:


  10. Comparing JSON and XML Formats of Collections

    From the Contacts API column, click "Contacts" and compare the XML and JSON responses. In the XML response, the individual contacts are children of the contacts element. In the JSON response, each connection is an object in the contacts array.

  11. Identifying Errors

    In the URI text field, delete a character from your GUID and click Make Request. The error response gives you a description of the problem, and the response header returns the HTTP status code 403 confirming that the request failed.

Table of Contents