clearspring - the widget network.

Platform Services Developers About Us Sign In Create Account

Platform

You are here: Docs → Guides → Implementing the Catalog API
 

Implementing the Catalog API

What is this?

The Catalog API is a powerful set of REST-based services that allows developers the ability to create a widget gallery using widgets from the Clearspring Platform.  Using the Catalog API developers can request the list of available widget on the Clearspring Platform.  Leveraging the list of widgets developers can create custom widget gallery views to be made available to their users.

This guide provides an overview and information on how to use the Catalog API to accept widget feeds from Clearspring

Who's this for?

This guide is primarily for developers who are tasked with integrating the Clearspring Catalog API into their widget catalog. To access the Catalog API Feed requires a Catalog API Key that is different from the user API Key for your account.  Please contact Clearspring to obtain a Catalog API Key

Developers should read the “Platform Integration Guide - Supporting Widgets” guide so that widgets within your gallery can easily be posted to your site.   This document can be found here

The Catalog API

The Clearspring Catalog API provides the ability:
•    to discover and add new widget content to your site
•    to display details about widgets
•    to get the code for users to install widgets

Launchpad Menu

 

Let the world know you’re ready for widgets 

Companies ready to accept widgets can partner with Clearspring to be added to the Launchpad menu.  Widget creators that choose to share their widget with a service can make the widget also available via the Catalog API feed.  The widget creator can track the growing number of users from the service and have a common place to find new offerings for promotion, monetization, or improving their widget with these communities. The services get a constant feed of new widgets and an eager development community.

Catalog API walk through

CatalogAPIFlow
  1. Widget creators publish their widgets into the Catalog API via the Widget Console
  2. Catalog API subscriber request the Catalog API Feed indicating any filter arguments
  3. Clearspring generates the appropriate Catalog API Feed and returns the feed
  4. The subscriber processes the feed and renders the widgets into the gallery
  5. When a user selects a widget from the gallery the subscriber simply invoke its own URL Exchange process passing the code from the Catalog API
NOTE: In some rare cases the widget will not be able to be configured on the widget itself or through menus provided by the Catalog API.  In those instances the widget placed into the Gallery will be a “default” version of the widget, which will need to be configured by the user on the widget creator’s site.  Clearspring will handle getting the remote configuration to appear on the widget placed on your site.

Customize Your Catalog API Feed

So how does it work? The Catalog API feed is an RSS formatted XML feed containing all the information needed to build a widget gallery without having to load any actual widgets. The feed includes information such as the widget identifiers, icons, thumbnails, descriptions, versions, dates, etc. (see detailed list below) for loading the widget, as described in the “Platform Integration Guide - Supporting Widgets”. Subscribers can filter and sort the incoming list of widgets and choose the content that best fits their community. Widgets that are accepted can easily be parsed and added to the gallery.

Filtering the Catalog API Feed

The Catalog API provides the ability to filter the feed based on the subscribers needs.  Filtering is supplied as a parameter to a the feed, for example:

https://services.clearspring.com/catalog/v1/list?apikey=9zTN1Ra&type=html&category=news

The result of the service call is an RSS document that includes all the widgets that match the parameters submitted.  The result set is limited to only 1024 widgets per RSS feed.  To determine if your result set will be greater then 1024 widgets use the following service:

https://services.clearspring.com/catalog/v1/count?apikey=9zTN1Ra&type=html&category=news

The result of the count service is an XML document that provides the total number of widgets found for that filter and the maximum number of widgets allowed to be pulled.  It is suggested that you request the total number of widget for your request then make your request with the start and count parameters page through your list, if it is greater the 1024 widgets.

The following table provides the list of parameters available for filtering the Catalog API feed.  These parameters can also be used with the count service.

Parameter Description
Apikey (required)  
API key string provided. Query for widgets developed or shared are made available.  Note: Accessing the Catalog API Feed requires a Catalog API Key that is different from the user API Key for your account.  Please contact Clearspring to obtain a Catalog API Key.
minCreated
A long representing Unix time. Only widgets created after the given time will be returned.
maxCreated 
A long representing Unix time. Only widgets created before the given time will be returned
minModified
A long representing Unix time. Only widgets modified after the given time will be returned
maxModified
A long representing Unix time. Only widgets modified before the given time will be returned
maxheight
 Filter out widgets whose height is greater then this value. Resizable widgets will be included
type
 The programming type of the widget.  Specify a list, comma separated, of only the included types: TYPE = flash | html | js | blob
authorEmail
 Limit the list of widgets to the author(s) email equal to any value (comma separated list)
authorName
 Limit the list of widgets to the author(s) name equal to any value (comma separated list)
minWidth
Filter out widgets whose width is no less then this value. Resizable widgets will be included
maxWidth
 Filter out widgets whose width is no greater then this value. Resizable widgets will be included
minHeight
Filter out widgets whose height is no less then this value. Resizable widgets will be included
maxHeight
Filter out widgets whose height is no greater then this value. Resizable widgets will be included
category
 List only widgets in a category(s).  Multiple categories are comma separated
premium
 If set to 1, then only return widgets from Premium widget creators.  If this is not set, then ALL widget will be returned.
start
 Use this as the starting index of the paging feature when filtering for widgets that return a large list
count
 Use this as the number of widget to return from the start value of the paging feature
The following are some examples filter requests:

  • Find all flash widgets from the authors Widget Builders and Jane Doe:
https://services.clearspring.com/catalog/v1/list?apikey=9zTN1Ra&type=flash&authorName=Widget%20Builders,Jane%20Doe
  •  Find all premium content only:
https://services.clearspring.com/catalog/v1/list?apikey=9zTN1Ra&premium=1

Catalog API Feed Format

The result of a Catalog API call is an RSS file with the list of widget.  The file format will encompass the following:

Parameter Description
 title The title of this RSS feed (default: Clearspring Widget Feed)
 link
 The URL used to retrieve this RSS feed (default: http://services.clearspring.com/catalog/v1/list)
 description
 Information about this field (default: Clearspring Widget Feed)
 lastBuildDate Date this files was created and retrieved
 language The language the file contents is presented (default: eng-US)
 ttl The length, in minutes in which this RSS file is valid (default: 720)
 item Information about each widget found – see next table
The following information is available for each widget:

Parameter Description
 title Widget title as defined by the creator
 description
 Detailed description of the widget as defined by the creator
 link
 Link to the widget home page. If the creator disabled this capability the link will be to widget.bs file for rendering
 author Email address of the widget creator
 enclosure URL to the widget image
 pubDate Date in which the widget was first added to the Catalog API feed
 widgetId Widget ID
 guid Globally unique ID
 widget:width Default width of the widget
 widget:height Default height of the widget
 widget:screenshot URL to the screenshot of the widget
 widget:icon URL to a 16x16 icon image of the widget
 widget:category The name of the category in which the creator assigned the widget (default: MISC)
 widget:srcURL Generic callback URL to the widget that does not create a placement ID – NOTE: this tag has been deprecated. Us widget API services and the WID (guid tag) to obtain the widget
 widget:config Denotes user-facing parameters that should be passed to the APIs when creating placements. This section is not present for non-configurable widgets.
The following attributes are made available for each user configurable parameter:
Parameter Description
 name Name of the parameter
 label
 User facing label of the parameter
 default
 Default value of the parameter
 type Type of value for the parameter.  This can be string, number, Boolean or list.  This can be used to validate input or provide assistance to the user at input time.

The feed is an RSS file with custom xmlns:widget tags that provide information about the widget(s).  The following is a sample of a feed.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:widget="http://www.clearspring.com">
<channel>
  <title>Clearspring Widget Feed</title>
  <link>http://ds00.dev.testspring.com/catalog/v1/list?type=flash</link>
  <description>Clearspring Widget Feed - Beta</description>
  <lastBuildDate>Mon Jun 16 07:04:46 CDT 2008</lastBuildDate>
  <language>en-us</language>
  <copyright>Clearspring Technologies</copyright>
  <ttl>720</ttl>

  <item>
    <title>LoveScopes</title>
    <description>What's in your love life? Find out with this specialized astrology widget!</description>
    <link>http://www.clearspring.com/widgets/463a656a1ea70875</link>
    <author>nbcu.widgets@gmail.com</author>
    <enclosure type="image/png" length="0" url="http://img.clearspring.com/images/463a656a1ea70875/img128x128.png" />
    <pubDate>Mon, 16 Jun 2008 09:06:25 -0400</pubDate>
    <guid isPermaLink="false">463a656a1ea70875</guid>
    <widget:widgetId>463a656a1ea70875</widget:widgetId>
    <widget:width>390</widget:width>
    <widget:height>284</widget:height>
    <widget:screenshot>http://img.clearspring.com/images/463a656a1ea70875/img300x250.png
</widget:screenshot>
    <widget:icon>http://img.clearspring.com/images/463a656a1ea70875/img16x16.png
</widget:icon>
    <widget:category>LOVE</widget:category>
    <widget:srcURL>http://api.clearspring.com/current/g/generic/463a656a1ea70875/generic.xml
</widget:srcURL>
    <widget:config>
      <widget:param name="userSign" label="Sign" type="list" default="Aquarius">
        <widget:option label="Aquarius" value="Aquarius" />
        <widget:option label="Aries" value="Aries" />
        <widget:option label="Cancer" value="Cancer" />
        <widget:option label="Capricorn" value="Capricorn" />
        <widget:option label="Gemini" value="Gemini" />
        <widget:option label="Leo" value="Leo" />
        <widget:option label="Libra" value="Libra" />
        <widget:option label="Pisces" value="Pisces" />
        <widget:option label="Sagittarius" value="Sagittarius" />
        <widget:option label="Scorpio" value="Scorpio" />
        <widget:option label="Taurus" value="Taurus" />
        <widget:option label="Virgo" value="Virgo" />
      </param>
    </widget:config>
  </item>
...
 </channel>
</rss>

The list of widgets returned will be all widgets that have been published to the Catalog API and that do not have hidden parameters.

Working with Catalog Widgets

Now that you have your list of widgets for a gallery there are some API calls that will make working with the widgets easier.  

Widget Descriptor

The widget descriptor is an XML formatted document, which provides details about a specific widget.  The XML document is formatted based on the Google Gadget XML (see http://code.google.com/apis/gadgets/docs/reference.html for more details). 

Getting a widget descriptor will create a placement if a placementId is not passed into the service call. The value of the parent placement is either bet the parentId passed to the call or the seed placement for the apiKey. When a new placement is created the configuration for that placement is value of the config parameter (see below).

To get the widget descriptor use the following service call:

https://services.clearspring.com/widget/v1/getDescriptor?apikey=9zTN1Ra&widgetId=463a656a1ea70875

The following table provides the list of parameters available:

Parameter Description
 apiKey (required) The API key that was used to get the catalog feed
 widgetId (required)
 Widget ID obtained from the guid tag of the catalog feed.  If widgetId is the only parameter a new placement is created.
 placementId
 Placement ID of the widget.  If set then the result set is the data for that specific placement, no new placement created.
 parentId Parent placement ID of the widget.  When set, with just the widgetId, will create a new placement with that parent.  If the parentId provide is not valid an error will be returned.
 config Configuration parameters of the widget, for the placement, as a URL encoded key value pair string
 fmt Format of the response – xml (default), json or kv

The response to this service call is defined by the request.  An example XML (default) response is as follows:

<Module>
  <ModulePrefs title="LoveScopes" title_url="http://www.clearspring.com/widgets/463a656a1ea70875" 
      author="NBCU" author_email="nbcu.widgets@gmail.com" author_affiliation="Unknown" 
      description="What's in your love life? Find out with this specialized astrology 
      widget!" screenshot="http://img.clearspring.com/images/463a656a1ea70875/img300x250.png" 
      thumbnail="http://img.clearspring.com/images/463a656a1ea70875/img16x16.png" 
      provider="Clearspring" providerWidgetId="463a656a1ea70875" providerUniqueId="47d886634f59dc5c_4857a65813a3dbbe" 
      category="Love"/>
  <Content>
    <!--[if IE]><object width="390" height="284" type="application/x-shockwave-flash" quality="high" 
    id="W47d886634f59dc5c4857a65813a3dbbe"><param value="http://services.clearspring.com/o/463a656a1ea70875/4857a65813a3dbbe/47d88663e4c15e3/f40fe487" 
    name="movie"/><![endif]--><!--[if !IE]>--><object type="application/x-shockwave-flash" 
    data="http://services.clearspring.com/o/463a656a1ea70875/4857a65813a3dbbe/47d88663e4c15e3/f40fe487" id="W47d886634f59dc5c4857a65813a3dbbe" height="390" 
    width="284"><!--<![endif]--><param value="transparent" name="wmode"/><param value="all" name="allowNetworking"/><param value="always" 
    name="allowScriptAccess"/></object>
  </Content>
</Module>

The XML response should look familiar if you have implemented URL Exchange with Clearspring.

Widget Code

The service required provides the necessary code to render the widget on an HTML page.  Widget type will determine the code returned.  If the widget is Flash then the code returned will be an HTML object tag.  If the widget is either HTML or JavaScript then the code returned will be an iFrame document. And finally if the widget is an arbitrary blob then the code returned will be the blob with the Clearspring tracking bug.

To get the widget code use the following service call:

https://services.clearspring.com/widget/v1/getCode?apikey=9zTN1Ra&widgetId=463a656a1ea70875

The following table provides the list of parameters available:

Parameter Description
 apiKey (required) The API key that was used to get the catalog feed
 widgetId (required)
 Widget ID obtained from the guid tag of the catalog feed.  If widgetId is the only parameter a new placement is created.
 placementId
 Placement ID of the widget.  If set then the result set is the data for that specific placement, no new placement created.
 parentId Parent placement ID of the widget.  When set, with just the widgetId, will create a new placement with that parent.  If the parentId provide is not valid an error will be returned.
 config Configuration parameters of the widget, for the placement, as a URL encoded key value pair string
 fmt Format of the response – xml (default), json or kv

The response to the service call is defined by the request.  An example XML (default) response is as follows:

<response>
  <message>Ok</message>
  <response>
    <code>
      <!--[if IE]><object width="390" height="284" type="application/x-shockwave-flash" quality="high" id="W47d886634f59dc5c4857b23bc23bd5d7">
         <param value="http://services.clearspring.com/o/463a656a1ea70875/4857b23bc23bd5d7/47d88663e4c15e3/61f2e4e2" name="movie"/>
      <![endif]-->
      <!--[if !IE]>--><object type="application/x-shockwave-flash" data="http://widgets.dev.testspring.com/o/463a656a1ea70875/4857b23bc23bd5d7/47d88663e4c15e3/61f2e4e2" 
         id="W47d886634f59dc5c4857b23bc23bd5d7" height="390" width="284"><!--<![endif]-->
      <param value="transparent" name="wmode"/><param value="all" name="allowNetworking"/>
      <param value="always" name="allowScriptAccess"/></object>
    </code>
    <pid>4857b23bc23bd5d7</pid>
    <wid>463a656a1ea70875</wid>
  </response>
  <status>0</status>
</response>

Widget in an iFrame

There are times when it is best to simply iFrame with widget, regardless of the widget type.  This service call allow for getting the iFrame code for the widget.  This method will also create the placement for the widget, similar to the getCode call above.

To get the widget iFrame code use the following service call:

https://services.clearspring.com/widget/v1/getFrame?apikey=9zTN1Ra&widgetId=463a656a1ea70875

The following table provides the list of parameters available:

Parameter Description
 apiKey (required) The API key that was used to get the catalog feed
 widgetId (required)
 Widget ID obtained from the guid tag of the catalog feed.  If widgetId is the only parameter a new placement is created.
 placementId
 Placement ID of the widget.  If set then the result set is the data for that specific placement, no new placement created.
 parentId Parent placement ID of the widget.  When set, with just the widgetId, will create a new placement with that parent.  If the parentId provide is not valid an error will be returned.
 config Configuration parameters of the widget, for the placement, as a URL encoded key value pair string
 fmt Format of the response – xml (default), json or kv

The response to the service call is defined by the request.  An example XML (default) response is as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <response>
    <message>Ok</message>
    <response>
      <code>
       <iframe width="390" height"=284" src="http://services.clearspring.com/placement/v1/view?wid=463a656a1ea70875&pid=4857b32d457ead79&ppid=47d88663e4c15e3"></iframe>
      </code>
      <pid>4857b32d457ead79</pid>
      <wid>463a656a1ea70875</wid>
    </response>
    <status>0</status>
  </response>

Creating a Gallery

This section provides the basic high-level steps of how to use the services describe to create your Widget gallery.

  1. First you will need to determine which filters to want to use.  For example, is there a specific category, do you want premium widgets only, is there a specific type you want, etc.
  2. Call the count service to determine the total number of widgets that your filter will return.  It is recommended that you always ask for the widget count prior to requesting the list, so that you can iterate through the list accordingly.
  3. Construct the list request with your filter and the start and count parameters, if needed.
  4. Make the call to request the list of widgets and get the XML feed.  Process the XML to generate your Gallery page.
  5. On the gallery page, for each widget add an “Add Widget” button to allow your users to grab the widget.
  6. When the user clicks the “Add Widget” button you will call the getCode service to obtain the specific widgets code for the user to add to their page.

Use these steps as a guideline to building your widget using the Clearspring Catalog API.

Next Steps

The following steps should be followed to start the process of integrating your widget gallery with the Clearspring Catalog API:

  1. Engage Clearspring to obtain a Catalog API key, for subscribing to the Clearspring Catalog API feed.
  2. Review the “Platform Integration Guide - Supporting Widgets” guide so that widgets can be posted to your site.  This document can be found at: http://www.clearspring.com/docs/guides/supporting-clearspring-widgets-on-your-site
  3. Develop support, in your widget gallery, for accepting the Catalog API XML document (see above) returned by feed.

Questions / Comments / Concerns

We welcome and encourage all feedback in this process.
Please feel free to reach us through here

Overview
Docs
Forum