Keyvan Nayyeri

Co-authoring a book about Community Server and being a Community Server MVP, I’m supposed to be a good resource about Community Server, especially its development, but my time limitations have not allowed me to work more on this aspect of my capabilities and share such stuff. However, as I find open doors in front of my eyes, I try to return to my life before the service and restore everything!

Prior to start serving in the armies and becoming a Second Lieutenant, I had a very popular blog post series/tutorials about Community Server development called CS Dev Guide in which I was covering main aspects of Community Server API in details, and those posts could be (and still are) a good resource for their own.

But Community Server 2008 is a revolution in the area of Community Server API because it introduces a new RESTful API system along refinements to the existing API that make it easier to develop applications, add-ons and components based on rich Community Server APIs that belong to Community Server, a powerful social networking platform, so it’s essential to be able to use its potential to extend different features as you like.

Regarding this introduction, I decided to start a new post series covering Community Server REST API and discuss some main aspects of this RESTful development in a few posts. Current post is the first part of the series that mainly helps you understand its structure, get familiar with its organization and how to use it.

Before starting, I have to point that Telligent has done a great job wrapping up a good documentation about REST API on Community Server site that can guide you in this area.

REST in Community Server

Of course, I doubt you can call yourself a developer if you don’t know what REST API is, at least generally, so I don’t talk about it at all and directly go to the implementation of REST API in Community Server.

Preceding versions of Community Server contained some web services to work with blogs (MetaWeblog API) or photo and file galleries but they were only discrete portions of features requested by users, and were not supposed to add much to the development and extensibility of the product. Actually they were rather some means to ease the user interaction with the site through client-side applications.

But Community Server 2008 came with a new major feature that fundamentally changes the way that developers could develop many applications for the platform, and that was, the addition of RESTful API for main operations and tasks that allow you perform all the common operations using a client application that works with the application server.

Here it’s important to note that REST API is not supposed to replace the use of built-in API in your applications, add-ons and components. This rich set of RESTful API is included to simplify some operations that were taking much effort from developers. Moreover, they come handy when it comes to interoperability scenarios. But most likely this REST API can replace the use of built-in APIs in many existing applications, add-ons and components. For example, I’ll release the next version of my BlogML converter as a Windows application based on the REST API because it has some advantages such ease of use, ease of installation and removing the extra load on server.

Community Server REST API is built on top of ASP.NET web services and like any other RESTful API requires an API key which is a unique string assigned to individual clients to build their unique URIs.

There are several URI patterns to build your resource URI requests and use the API in Community Server. Online documentation is what you need to get started with these patterns, so I don’t talk about it here. Moreover, in a moment you’ll read that you don’t need to deal with these details because there is a supplemental web service client library included as a part of Community Server.

Enable the REST API on Server

An infancy of Community Server API development is enabling the REST API in your application because by default it’s disabled. There is a complete integration between the server-side API, Community Server membership and role system, and RESTful APIs behind the scenes in which you must be a registered user on a Community Server site in order to be able to use the API, and you must grab and use your own API key, so everything happening with your API key will happen with a relationship with your user to guarantee the security. Likewise, Community Server only allows a user to use your API key with applications that he or she has access to, so if a user or role that uses your API key doesn’t have access to photo galleries then he’s not able to use this part of the REST API as well.

Having this important background, the first step in using the REST API is, enabling the REST API in your application that is possible by navigating to http://Site.Com/controlpanel/tools/ManageRest.aspx, a page that is accessible to site administrators. Here you see an option to enable the REST API for your site, and there is also a set of available roles in your application that can access to the REST API.

Here not only you need to enable the REST API but also you may require to enable some roles to have access to the API. You must do this on your own risk and regarding the access level of your users and roles.

For example, I enable BlogAdministrator role and WikiAdministrator role to have access to the REST API.

Grab an API Key

After enabling the REST API in your application, you need to grab your own API key that will be used to build your request URIs. Community Server assigns API keys to individual users.

You can retrieve your own API key from your profile by navigating to http://Site.Com/user/MyApiKeys.aspx (alternatively navigate to your profile page, Site Options tab, and then click on Create and Edit Application Keys link at the bottom). Here you can get an API key just by entering the name of your application. The name doesn’t matter and is used to  keep track of all applications on a site.

Note the randomly generated unique string value as API key for your application that will be used as an inherent part of your development with Community Server REST API. As long as this API key is available on your site and is enabled, you can use REST API on clients to access to some parts of the site where a user or his role has access to.

Client-Side Development

But the main part of the work is on client side where you need to apply the API and implement your logic.

Community Server REST API generates XML response on HTTP protocol (like many common RESTful APIs) and there are various XML structures that you need to deal with. Obviously this is not easy and something preferred by developers, so there is a rich client-side library that ships with Community Server and saves you from working directly with low level XML responses. This library is encapsulated in a single assembly called CommunityServer.WebServices.dll that is available in bin folder in your Community Server download package.

Community Server API and the client library work based on two parameters: username and API key, so you always need to provide these three parameters along some specified information to be able to authorize your requests and use the API.

In an upcoming post, I’ll give more details about the client library and its structure, and will continue the discussion with a main focus on the library because it’s the most common way to develop your applications for Community Server.