Developers : SOAP API

The Faves SOAP API provides an easy to use API when combined with tools for generating class stubs from WSDL files.

Getting Started

This section contains a basic overview of getting started with the API using various popular development environments.

All Environments

The Faves SOAP API should be usable from any development environment with networking capabilities. SOAP libraries, and tools which can generate class / service client stubs from the API's WSDL file will ease development considerably.

Be sure your client library supports HTTP Basic authentication (this is how we determine your Faves identity), and can communicate using SSL-encrypted HTTP.

.NET Framework SDK

The .NET Framework SDK ships with a tool called "wsdl.exe", which can be used to generate classes from a WSDL URL. To generate stubs for Faves' SOAP API, run the tool as follows (Replace [username] and [password] with your Faves credentials, and adjust the tools path as necessary):

"%PROGRAMFILES%\Microsoft.NET\SDK\v2.0\Bin\wsdl.exe" /u:[username] /p:[password] https://secure.faves.com/BlueDotApi.asmx?WSDL

The tool will write a file called BlueDotWebService.cs, containing definitions for the types and methods.

To use the service, you'll need to set your credentials as demonstrated below:

BlueDotWebService service = new BlueDotWebService();
service.Credentials = new NetworkCredential("[username]", "[password]");
TagCloudItem[] items = service.GetTags();

Visual Studio

From the Visual Studio "Project" menu, select "Add Web Reference". Enter the URL:

https://secure.faves.com/BlueDotApi.asmx?WSDL

When prompted, enter your Faves credentials. Click the "Add Reference" button to add the reference, and build your project. You can now invoke the service methods as described in the .NET Framework SDK sample.

Download a sample project demonstrating API usage. This project was created using Visual C# 2005 Express Edition. The project can also be built using only tools shipped with the .NET Framework (simply run msbuild.exe from the project root).

Methods

The following methods are available as part of the Faves SOAP API.

FriendList[] GetFriendLists()

This method returns a list of the user's friend lists. Use the result of this method to associate friend list names with the IDs returned in search results.

datetime GetLastUpdatedDateTime()

Returns the date and time of the user's last Fave. This can be useful for constructing search constraints.

TagCloudItem[] GetTags()

Returns a list of all tags for the authenticated user, with counts representing the number of Faves to which the tag has been applied.

void RenameTag(string oldTag, string newTag)

Renames a tag. The old tag will be treated in a case-insensitive manner, and all tags will be changed to the new tag with specific casing. Thus, calling RenameTag("Java", "java") will rename all instances of "java" (regardless of case) to "Java". Use null to delete the tag.

SearchResult Search(Search search)

Executes a search based on the provided criteria. A Search object with no criteria (null is invalid) will search all Faves in reverse chronological order (newest first). This method will return up to 10 results at a time, and will provide the total number of results so the caller can determine whether or not to request the next page.

Types

The following data types are used by the Faves SOAP API. Classes to represent these types can easily be generated using the WSDL file.

TagCloudItem

Represents a tag and indicates the number of times that tag has been used.

Properties
Name Type Description
Tag string The name of the tag.
Count unsigned int32 The number of Faves on which the tag has been used.
DotPermission

Represents the permission scope of a Fave (which Faves visitors can see the Fave).

Properties
Name Type Description
IsPublic bool True if the Fave is viewable by all Faves users (Everyone).
IsPrivate bool True if the Fave is visible only to its creator.
IsAllFriendsScope bool True if the Fave is available to its creator's entire community.
FriendListIds int32[] An array of friend lists IDs to which a given Fave has been published.
Fave

All information about a single Fave.

Properties
Name Type Description
Id string The Fave's unique identifier.
Url string The URL of the content the Fave references.
Subject string The Fave subject, often the title of the referenced page.
Note string The user's personal note on the Fave.
Tags string A list of the user's tags, comma separated.
Rating int32 Content rating, can be 0-5.
ThumbnailImageUrl string URL containing a thumbnailed image.
ThumbnailImageWidth int32 The width of the image thumbnail (maximum 125).
ThumbnailImageHeight int32 The height of the image thumbnail (maximum 125).
CommentCount int32 The number of comments on the Fave.
Created datetime The date the content was created.
LastUpdated datetime The date the content was last updated.
Permission DotPermission The permission scope of the Fave.
SearchResult

Represents the results of a search executed using the Search() method.

Properties
Name Type Description
ServerTime datetime The current date and time according to the server.
DotCount int32 The total Fave count for the given search (can be used to determine whether or not to request another page).
Faves Fave[] The Faves (maximum of 10) for the current result page.
DateRange

A date range.

Properties
Name Type Description
StartTime datetime The beginning of the date range.
EndTime datetime The end of the date range.
FriendList

Represents a user's friend list.

Properties
Name Type Description
Id int32 The unique ID of the friend list.
Name string The name of the friend list.
Search

A search specification.

Properties
Name Type Description
CreationDateRange DateRange Limits search results to those in the given date range (inclusive).
Tags string[] A list of tags to limit the search results by. All provided tags must exist for the Fave to be returned.
Keywords string[] A list of keywords to match (will match tags or content within the user's note). All provided keywords must be found for the Fave to be returned.