Start Development with Community Server REST API
In the first part of a new post series about Community Server REST API, I introduced this API, its structure, how to enable it, and how to grab your own API key. I also pointed to the necessary assemblies that you should reference in your projects in order to be able to develop applications based on this API.
The current post, the second part, gets you started with developing client applications for Community Server REST API and how to develop something that works with Community Server REST API to simplify a task.
The last post showed you how to reference CommunityServer.WebServices.dll in order to get access to simplified API provided as a built-in part of Community Server and avoid working directly with XML data directly. Here I focus on this library, too.
One of the very important benefits of Community Server REST API is the capability to build any type of application on top of this infrastructure. Prior to Community Server 2008, it was arduous to integrate a Windows Form or Console application with Community Server, even it could be difficult to integrate a web application in some circumstances.
On the other hand, in Community Server 2008 new REST API allows you to build any type of application on any platform and integrate it with your Community Server instance easily. For example, you may want to build a Windows application that simplifies and speeds up the process of managing your users or roles, and this is all possible with REST API in a few steps.
The Structure
The first topic that I would discuss is the structure of Community Server services library in which you can deal with a variety of features remotely including blogs, forums, groups, media galleries, membership and role management, search, and site settings. These sections are grouped into separate namespaces which allow you to work with them easily. For example, APIs related to blogs are in CommunityServer.WebServices.Blogs namespace, and APIs for forums are in CommunityServer.WebServices.Forums.
The logical separate of these portions is analogous to the original Community Server APIs and they follow the same pattern in their structure and methods. Therefore, there is a CommunityServer.WebServices.Common that leverages common features and classes in the library, and is something similar to CommunityServer.Common namespace.
Each of these namespaces contains a set of classes, interfaces, and enumerators that offer the means that you need to deal with Community Server.
This separation in the library allows you to work with the API efficiently, and helps you apply your existing knowledge in Community Server to build your applications.
Beside the main namespaces available in the library, you see corresponding namespaces for serialization/deserialization of the objects being sent/returned from the service. You wouldn’t care much about them because they’re used behind the scenes. Therefore, you see that all the namespaces are grouped into a set of namespace pairs in which one namespace provides the user level API, and another enables serialization/deserialization of objects.
Service Proxy Classes
The basis of this library are some service proxy classes that provide the main properties and methods to work with objects. In main Community Server API, you have access to a set of classes that present an object as well as a set of related classes with static methods that allow you to deal with these objects. For example, WeblogPosts class helps you get, add, delete or edit a WeblogPost object or a list of these objects. This model is slightly different in REST API library, and it’s centralized in service proxy classes in each application, so all these common operations for blogs application can be done with BlogService library.
Therefore, in this library you have some main service proxy classes including Service, BlogsService, ForumsService, GroupsService, MediaGalleriesService, MembershipService, SearchService, and SiteService. All these classes are derived directly from ServiceBase class, and provide a wide range of methods and properties to work with other classes in their area.
Besides, you can get access to same methods directly from your classes as a simpler alternative. For example, BlogsService has a AddComment method that allows you to add a comment to specific blog post by its ID, and BlogPost class has an AddComment method that does the same job.
Having this background, now you should know that these service classes have a vital responsibility in REST API library, and you would try to focus more on them. These classes may have some properties as well in which you usually get an instance of the objects that ease your development. For example, Service class (in CommunityServer.WebServices namespace) has a few properties that return relevant object instances of other service proxy classes such as BlogsService or ForumsService.
Programming Model
Another basic element in learning the Community Server REST API, especially its client library, is understanding the programming model in the library. Luckily, this library follows the same programming model as main Community Server API (with some differences that I mentioned above in the area of operations), so if you’re already familiar with the programming model, then you can start development without any problem.
The programming model consists of creating a service proxy class (which requires a username, an API key, and the URL of the site), using the methods and properties in the class to perform some operations, logical modification and processing of the data in your classes, and finally using the appropriate methods in service proxy classes (or other classes) to save your changes/additions. This process may be shorter if you only need to get the data, though.
If you’re already familiar with service/client programming, then there is nothing special for you but if you haven’t had much experience with this model, then you need to practice in this field.
As is obvious, here you don’t have access to the current context in Community Server instance to have access to some banal information like the current user, or others stuff. REST API is designed to accomplish different goals, so if you’re going to, for example, work with Community Server URLs, then REST API is not your choice.
Sample Application
Theory discussions in the field of programming is like trying to learn soccer without hitting the ball, so a simple piece of code can supplement all my above paragraphs!
Knowing some principles about Community Server REST API that I have mentioned in the last post and the current post to this point, and having a good understanding of the Community Server architecture, you would be able to start development with Community Server REST API library but a start point may help you in infancy.
Here I create a Console Application in which I just want to perform a simple task, and that task is, listing the name of all available blogs on my Community Server site. After referencing CommunityServer.WebServices assembly, I can use the following code to accomplish this goal.
static void Main(string[] args)
{
Console.Title = "Start Development with Community Server REST API";
Service service = new Service("http://localhost/cs/", "admin", "2nw9q0ki");
PagedList<Blog> blogs = service.Blogs.GetBlogs();
foreach (Blog blog in blogs)
{
Console.WriteLine(blog.Name);
}
Console.ReadLine();
}
This code is self-explanatory but there are a few points that I would mention. The first point is about the construction of Service object instances (which is similar for all other service proxy classes) where I have passed three parameters to the public constructor. First parameter is the URL of the site, second parameter is the username that I want to use, and the last parameter is my API key (that I retrieved in the last part).
Alternatively, I could directly use BlogService class to perform the same task even though the current code is also using this class where I use Service.Blogs property.
You see how simple it is to use the Community Server REST API library. In the future parts I try to cover further details, principles and techniques about this component.
[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 : 10.29.08
#1
Community Server REST API - Blogs
11.17.2008 @ 3:12 PM
In the first two parts of this post series about Community Server REST API I introduced the API and covered