Community Credit Service Library 1.0
I wrote that it's a very short while that I have appeared on Community Credit to add my community contributions to the great database of this site. Dave was also kind enough to introduce me as the featured community leader in the latest newsletter issue.
When I announced my appearance on the site, I also announced a new CodePlex project to build a C# library to work with Community Credit web-services to automate the process of working with site and adding credits to the database.
In this short while, I've been working on the library smoothly. Initially I had no idea how helpful such a library can be because never worked with Community Credit web-services before.
Overview
Unfortunately Community Credit web-services aren't very simple and easy to use and are ambiguous to some extent. In general these web-services could be designed in a simpler and better way. I've had some conversations with Dave about the web-services and gave him some suggestions for the next version of the site that is already in progress.
However, having such a library made sense for me more than the past because of the ease of development that every developer is looking for.
So regarding this problem there are some goals for this library that I list:
- Replacing various parameters and general return types for Community Credit web-services with .NET classes that represent main objects that play a role in web-services.
- Simplifying the work with methods in web-services by choosing more appropriate and simpler names, using overloads and other techniques.
- Hiding the underlying simple way of exposing web-service methods under a normal .NET library.
- Providing better tools to work with Community Credit APIs via some classes and objects.
- Using XML code comments for better explanation of what is going on.
- Using more appropriate data types for some parameters and properties because there are some inappropriate types used for original Community Credit web-services.
The first version of the library is now ready to answer to these goals. Even though the library has simplified the process of working with web-services but in my own opinion users may find some uncommon parts of the API hard to use and that is because of the nature of the web-services that couldn't be resolved in the API.
However, usually developers are looking for some common and specific methods in Community Credit web-services that are now easy to use with the library.
How to Use
By the way, I tried to keep everything self-explanatory via naming convention and XML code comments but users would have a basic understanding of Community Credit point system in order to be able to use the library in the best way.
Here I give a few examples of using the library to get you started.
First of all, you always need to create an instance of CommunityCredit object to be able to use this library. This class provides all methods that you need to work with Community Credit web-services.
To create an instance of this object you have two options. You can pass your own affiliate code and affiliate key to the constructor to be used for your methods or you can pass nothing to the constructor. In this case my own affiliate code and affiliate key will be used. This is suitable for those people who want to use the library for their small sites.
Beside the main CommunityCreditService class, there are some classes for different purposes available in CommunityCredit.Components namespace that are used as parameter or return types for methods provided in CommunityCreditService class. Some of these types are code representations of basic types that are used in Community Credit web-services like Earner, Task, TopEarner, Prize, PointCategory or NewsGroupItem while some other types are collection types for the basic types such as EarnersCreditCollection, PointCategoryCollection or PrizeCollection.
After creating an instance of the CommunityCreditService object, you can use its methods by passing appropriate types from CommunityCredit.Components namespace and for some functions you get some return types from this namespace.
For some public subroutines of the CommunityCreditService class exceptions of CommunityCreditException type may be thrown that specify the reason why the operation has failed so you need to consider this in your code.
As an example, below code submits credit for a medium length article to Community Credit and gets its parameters from an ASP.NET web form.
protected void btnSubmit_Click(object sender, EventArgs e)
{
try
{
// Use the default affiliate code and affiliate key
CommunityCreditService service = new CommunityCreditService();
Earner earner = new Earner(txtFirstName.Text, txtLastName.Text, txtEmail.Text);
PointCategory category = new PointCategory("Article");
Task task = new Task(txtTitle.Text, txtUrl.Text, category);
service.AddCommunityCredit(earner, task);
lblResult.Text = "Points Submitted!";
}
catch (CommunityCreditException ex)
{
lblResult.Text = ex.Message;
}
}
I think the code is easy to read. There is only one point to mention about PointCategory class. There is a hug list of various point categories on Community Credit site that you can retrieve via GetPointCategories method of CommunityCreditService class.
However, PointCategory has many properties that you normally wouldn't like to set to create a simple object to pass to some methods like AddCommunityCredit. For such cases I've provided a public constructor for PointCategory class that gets its Code property as parameter and creates a basic object instance with required properties. Code property is a unique string value for each point category that you can set by hand to retrieve from the GetPointCategories method.
The other point is about setting your first name and last name in methods. Community Credit web-services don't care if these values aren't equal to those that you've entered on the site to register but some values are required to use the service. They could be dropped from methods, though! But for email address you need to enter the exact same address as what you've used to register on Community Credit site.
As the second example I show you how to retrieve the list of codes for all point categories.
First I add a code like this to my .aspx page to show data in a Repeater control:
<div>
<h1>
The List of All Point Categories</h1>
<ul>
<asp:Repeater ID="categoriesRepeater" runat="server">
<ItemTemplate>
<li><strong>
<%# DataBinder.Eval(Container.DataItem, "Code")%></strong> :
<%# DataBinder.Eval(Container.DataItem, "Description")%>
</li>
</ItemTemplate>
</asp:Repeater>
</ul>
</div>
Now I add a simple code to my page's load event to retrieve the list of categories and bind Repeater control to this list.
protected void Page_Load(object sender, EventArgs e)
{
// Use the default affiliate code and affiliate key
CommunityCreditService service = new CommunityCreditService();
categoriesRepeater.DataSource = service.GetPointCategories();
categoriesRepeater.DataBind();
}
You see that most of the main methods of this library are easy to use like abovementioned examples. When working with the library you can also get the help from Intellisense to find description about different classes, methods and properties.
Download
You can download the binary and source code of the first release of Community Credit Service Library in separate packages from here.
Community Credit Service Library is licensed under a New BSD license so you can use it easily in your own applications and components.
Future
Looking at future, we would have a fresh new release in the next a few months because Community Credit is going to hit a total refreshment and new design in near future.
I gave my suggestions to David Silverlight about the new API and using new technologies and simpler methods to get things done. I'm pretty sure there will be very simpler and better APIs for the next version of the site so I need to redesign the library for them.
In the meantime and long time, I hope that all .NET communities apply Community Credit web-services to provide a built-in support for their user profiles to automatically add points for various tasks to the database. All they need is the email address and the rest can be done via codes in my library! This is something that can be implemented in some open source communities like DotNetKicks quickly.
There is also a Community Server 2007 add-on coming soon that can be used to enable such functionality for many .NET communities that are powered by this unique social networking platform. There is also an add-on for Community Server 2.1 already that is written by Simone.
At last, in the next couple of days I'll implement a plug-in for Graffiti to apply this library in order to automatically submit points to Community Credit for new Graffiti posts.
[advertisement] Axosoft OnTime 2008 is four developer tools in one: bug tracking, project wiki, feature management, and help desk. It manages your development process so developers can focus on coding. Installed or Hosted – Free Single-user license -- Free 30-day team trial.
1 Comment : 01.24.08
#1
CraigN.NET » Blog Archive » Submit to Community Credit 1.0 plug-in released
07.30.2008 @ 7:09 PM
Pingback from CraigN.NET » Blog Archive » Submit to Community Credit 1.0 plug-in released