Connecting to social network API's with Spring.NET Social
Connecting to social network API's with Spring.NET Social | OPEN For ALL
Spring.NET Social helps you to simplify authentication (OAuth) and API binding with Software-as-a-Service (SaaS) providers such as Facebook and Twitter. Spring.NET Social makes it easy to add support for service providers that are not already supported by the framework. If you review the existing client projects, such as Twitter, Dropbox, LinkedIn and Facebook, you will discover they are implemented in a consistent manner and they apply a set of well-defined extension points.
The process of adding support for a new service provider consists of several steps:
Create a source project for the client code e.g. Spring.Social.Twitter.
Develop or integrate a binding to the provider's API e.g. ITwitter.
Create an IServiceProvider model that allows users to authorize with the remote provider and obtain authorized API instances e.g. TwitterServiceProvider.
Creating a source project for the provider client code
We recommend the code for a new Social client code reside within the Spring.Social.{providerId} assembly, where {providerId} is a unique identifier you assign to the service provider you are adding support for.
Within the assembly, we recommend the following namespace structure:
Namespace Provider
Spring.Social.{providerId}.Api The public interface and types that defines the API binding.
Spring.Social.{providerId}.Api.Impl The implementation of the API binding.
Spring.Social.{providerId}.Connect The types necessary to establish connections to the service provider.
Here, the central service API type, ITwitter, is located in the Api namespace along with its supporting operations types and data transfer object types.
The primary implementation of that interface, TwitterTemplate, is located in the Api.Impl namespace (along with other internal types that have been excluded from this view).
Finally, the Connect namespace contains the implementations of the IServiceProvider that enable connections to Twitter to be established.
Designing a new API binding
API developers retain full control over the design and implementation of their API bindings.
That said, we offer several design guidelines in an effort to improve overall consistency and quality:
Favor separating the API binding interface from the implementation.
This is illustrated in the Twitter example in the previous section.
There, "Twitter" is the central API binding type and it is declared in the Spring.Social.Twitter.Api namespace with other public types.
TwitterTemplate is the primary implementation of this interface and is located in the Spring.Social.Twitter.Api.Impl namespace along with other internal implementation types.
Favor organizing the API binding hierarchically by RESTful resource.
REST-based APIs typically expose access to a number of resources in an hierarchical manner.
For example, Twitter's API provides access to "status timelines", "searches", "lists", "direct messages", "friends", "geo location", and "users".
Rather than add all operations across these resources to a single flat "Twitter" interface, the ITwitter interface is organized hierarchically:
public interface ITwitter : IApiBinding
{
IBlockOperations BlockOperations { get; }
IDirectMessageOperations DirectMessageOperations { get; }
IFriendOperations FriendOperations { get; }
IGeoOperations GeoOperations { get; }
IListOperations ListOperations { get; }
ISearchOperations SearchOperations { get; }
ITimelineOperations TimelineOperations { get; }
IUserOperations UserOperations { get; }
IRestOperations RestOperations { get; }
}
{
IBlockOperations BlockOperations { get; }
IDirectMessageOperations DirectMessageOperations { get; }
IFriendOperations FriendOperations { get; }
IGeoOperations GeoOperations { get; }
IListOperations ListOperations { get; }
ISearchOperations SearchOperations { get; }
ITimelineOperations TimelineOperations { get; }
IUserOperations UserOperations { get; }
IRestOperations RestOperations { get; }
}
IDirectMessageOperations, for example, contains API bindings to Twitter's "direct messages" resource:
public interface IDirectMessageOperations
{
IList GetDirectMessagesReceived();
IList GetDirectMessagesReceived(int page, int pageSize);
IList GetDirectMessagesReceived(int page, int pageSize, long sinceId, long maxId);
IList GetDirectMessagesSent();
IList GetDirectMessagesSent(int page, int pageSize);
IList GetDirectMessagesSent(int page, int pageSize, long sinceId, long maxId)
DirectMessage GetDirectMessage(long id);
DirectMessage SendDirectMessage(string toScreenName, string text);
DirectMessage SendDirectMessage(long toUserId, string text);
void DeleteDirectMessage(long messageId);
}
{
IList GetDirectMessagesReceived();
IList GetDirectMessagesReceived(int page, int pageSize);
IList GetDirectMessagesReceived(int page, int pageSize, long sinceId, long maxId);
IList GetDirectMessagesSent();
IList GetDirectMessagesSent(int page, int pageSize);
IList GetDirectMessagesSent(int page, int pageSize, long sinceId, long maxId)
DirectMessage GetDirectMessage(long id);
DirectMessage SendDirectMessage(string toScreenName, string text);
DirectMessage SendDirectMessage(long toUserId, string text);
void DeleteDirectMessage(long messageId);
}
Implementing a new API binding
API developers are free to implement their API binding with whatever REST/HTTP client they see fit. That said, Spring.NET Social's existing bindings such as Twitter all use Spring.NET REST Client Framework's RestTemplate.
RestTemplate is a REST client that provides a uniform object mapping interface across a variety of data exchange formats (JSON, XML, etc).
As discussed in the previous section, we recommend keeping implementation types separate from the public API types. We also recommend keeping implementation details internal.
The way in which an API binding implementation is constructed will vary based on the API's authorization protocol. For APIs secured with OAuth1, the consumerKey, consumerSecret, accessToken, and accessTokenSecret will be required for construction:
public TwitterTemplate(string consumerKey, string consumerSecret,
string accessToken, string accessTokenSecret)
{
...
}
string accessToken, string accessTokenSecret)
{
...
}
For OAuth2, only the accessToken should be required:
public GitHubTemplate(string accessToken)
{
...
}
{
...
}
Each request made to the API server needs to be signed with the authorization credentials provided during construction of the binding.
This signing process consists of adding an "Authorization" header to each client request before it is executed.
For OAuth1, the process is quite complicated, and is used to support an elaborate request signature verification algorithm between the client and server.
For OAuth2, it is a lot simpler, but does still vary across the various drafts of the OAuth2 specification.
To encapsulate this complexity, for each authorization protocol Spring Social provides a base class you may extend from to construct a pre-configured RestTemplate instance that performs the request signing for you.
For OAuth1:
public class TwitterTemplate : AbstractOAuth1ApiBinding
{
public TwitterTemplate(string consumerKey, string consumerSecret,
string accessToken, string accessTokenSecret)
: base(consumerKey, consumerSecret, accessToken, accessTokenSecret);
{
}
}
{
public TwitterTemplate(string consumerKey, string consumerSecret,
string accessToken, string accessTokenSecret)
: base(consumerKey, consumerSecret, accessToken, accessTokenSecret);
{
}
}
For OAuth2:
public class GitHubTemplate : AbstractOAuth2ApiBinding
{
public GitHubTemplate(string accessToken)
: base(accessToken);
{
}
}
{
public GitHubTemplate(string accessToken)
: base(accessToken);
{
}
}
Once configured as shown above, you simply implement call RestTemplate and implement the various API operations.
The existing Spring.NET Social client modules all invoke their RestTemplate instances in a standard manner:
public TwitterProfile GetUserProfile()
{
return this.RestTemplate.GetForObject("account/verify_credentials.json");
}
{
return this.RestTemplate.GetForObject("account/verify_credentials.json");
}
Latest release is 1.0.1
Home:
http://www.springframework.net/social/Download:
http://www.springframework.net/social/