Overview

Access to the new Community Server API comes in two formats. First, we have created a set of RESTful webservices that serve XML over HTTP. And second, we have wrapped these services into a C# library for those wanting to specifically target the .NET environment. Regardless of which method you choose, we look forward to the ways you will use the API to extend the Community Server platform.

Authentication

Similar to some other sites like Flickr, we've chosen to implement a system involving "API keys" to handle authentication with the webservice. Instead of requiring users to give the application their username/password and passing it with each request to the site, we've created API keys which are randomly generated tokens which allow webservice calls to be authenticated as the user.

Keys can be generated by logging into your account on the site, then click on the edit link next to your name to go and edit your profile. On the Site Options tab, the bottom contains a link for "Create and Edit Application Keys". On the My API Keys screen you will see a list of authorized applications that the user has granted access to. You can fill in a name for the API key so you can identify and manage it later, and click Generate. This will generate the new key and add it to the list.

When communicating with the webservice directly (ie, not using the supplied C# Client API), the combination of the username and key are passed to the webservice as an HTTP header. The name of the header is "Rest-User-Token" and the format a Base64 encoded string of "[apikey]:[username]". As an example, if you had a username "jdoe" and that user had an API key of "sdf323va", you would Base64 encode a string of "sdf323va:jdoe". The final header would look like:

Rest-User-Token: c2RmMzIzdmE6amRvZQ==

When using the C# client API, it provides methods to allow you to pass in the username and API key so you do not need to format the header manually.

Another capability of the authentication is the ability to impersonate another user. Users in the "System Administrators" role have the ability to impersonate another user using an additional header. This allows scenarios such as supporting building another front end to Community Server, and performing operations as a given user. When impersonating a user, the token is authenticated against the main user, however all permissions by the service method will be handled against the impersonated user, and the "current user" for the calls will also reference the impersonated user. To impersonate a user, add another header named "Rest-Impersonate-User" with a value of the username to impersonate. Using the previous example with user "jdoe" who is a System Administrator, to authenticate and impersonate the user "jsmith", they would need the following headers:

Rest-User-Token: c2RmMzIzdmE6amRvZQ==
Rest-Impersonate-User: jsmith

Impersonation is also supported when using the C# client API. The methods for specifying the username and ApiKey include an additional override that takes another parameter for the user to impersonate.

Client API

Before you make a blog post you will need to have user account that has access to write to a blog. If you haven't already generated an API key, as covered above, please generate one and make note of the key.

Next you will need to create a new project. Once you have your project created you should add a reference to the CommunityServer.WebServices assembly, which is named CommunityServer.WebServices.dll. In the class that you want to make calls to the Community Server service you should add a using statement like this:

using CommunityServer.WebServices.Blogs;

You can now begin using the blogs service. You will create a new instance of it like this;

BlogsService service = new BlogsService(siteUrl, username, apiKey);

Add Blog Post

Once you have the service constructed you can add blog posts quite easily. Here is a simple method that adds a blog post to the "johndoes_blog" blog. Please note that "johndoes_blog" is the application key for the users blog. You can get your application key by looking that the URL to your blog. The blog in this example is found at http://localhost/cs/blogs/johndoes_blog/default.aspx.

private static void AddBlogPost()
{
    BlogsService service = new BlogsService(siteUrl, username, apiKey);

    Blog blog = service.GetBlog("johndoes_blog");

    BlogPost post = new BlogPost();
    post.Title = "This is my first REST blog post";
    post.Body = "I don't have much to say, except that this is way cool";
    post.Date = DateTime.Now;
    post.Keywords.Add("Sample");

    service.AddBlogPost(post, blog.Id);
}

Get Blog Post

Since you just added a blog post you should be able to get the post from the service. To do this you can do something like the following method.

private static List GetBlogPosts()
{
    BlogsService service = new BlogsService(siteUrl, username, apiKey);
    Blog blog = service.GetBlog("johndoes_blog");

    return service.GetBlogPosts(blog.Id);
}

Now that I have these two simple methods, my application can call them in order and display the results to the console, like so.

static void Main(string[] args)
{
    AddBlogPost();

    List posts = GetBlogPosts();

    if (posts != null)
        foreach (BlogPost post in posts)
            Console.WriteLine(post.Title);
    else
        Console.WriteLine("No Posts found");

    Console.Read();
}

The output of running this program looks like this: This is my first REST blog post

Delete Blog Post

If you wish to delete the blog posts you can do so by running a method like the following. Notice that it is deleting all blog posts with the Tag="Sample" in the appropriate blog.

private static void DeleteBlogPost()
{
    BlogsService service = new BlogsService(siteUrl, username, apiKey);

    Blog blog = service.GetBlog("johndoes_blog");
    BlogPostQuery query = new BlogPostQuery();
    query.BlogId = blog.Id;
    query.Keywords.Add("Sample");

    List posts = service.GetBlogPosts(query);

    foreach (BlogPost post in posts)
        service.DeleteBlogPost(post.Id);
}