I’m simply bored with it.

Also, someone has already beaten me to it, and is writing something that is actually far superior to what I’d managed to push out. In my defence, I haven’t done very much anyway, so anything that is fairly substantial is going to look better by default.

So, I’m going to knock it on the head. I’ll leave the code, such as it is, up on Github.

var userApi = new UserApi();
var user = userApi.GetUser("example");

Pretty straightforward, right? What about the as yet unwritten GistApi?

var gistApi = new GistApi();
var gist = gistApi.GetGist(...);

Again, pretty straightforward. But I see a pattern forming. What am I going to do when it comes to the RepositoryApi?

var reposApi = new RepositoryApi();
var repo = reposApi.GetRepository(...);

Well, that is starting to look pretty fucking stupid. I’ve caught myself doing it with other methods as well. I simply cannot believe I’ve let myself be so stupid. At least there is not that much implemented where I’ll have to refactor loads of shit.

The typical way that you’d make a request with RestSharp:

1. Create a RestRequest
2. Create a RestClient
3. Execute the request with the client
4. Do something with the response.

It’s at the point that you get the client object that you may wish to add authentication. For example with a REST API such as Githubs, certain methods behave differently if the request is authenticated or not, so being able to magically turn on authentication is desirable.

To authenticate a request with RestSharp, it is a simple case of creating a RestRequest, RestClient and an IAuthenticator instance for the authenticating mechanism you want to use. For example:

var client = new RestClient
             {
                 BaseUrl ="https://api.github.com",
                 Authenticator = new HttpBasicAuthenticator(username, password)
             };

This is pretty straightforward and standard RestSharp usage. You may have a class to encapsulate this functionality, with a method which returns the RestClient instance, probably in a base class in order to inherit this common functionality in other classes.

public abstract class BaseApi
{
    RestClient GetRestClient()
    {
        ...
    }
}

Options

There are several methods which we can use to add authentication dynamically to the RestClient instance, ranging from the trivial to the more involved.

The trivial solution is to add the IAuthenticator as a parameter to the method, which is then assigned to the RestClient when it is created. Easy. Also fairly easy is just make it abstract or virtual and override it in an inheriting class, although this breaks SRP.

Alternatively, we can implement the Decorator pattern, and introduce the authentication in a class which is solely responsible for handing it. I’m not going to go into this in too much detail, there is a wealth of information on implementing this pattern already available on the web. Using a Decorator is valid in a lot of situations, particularly when re-factoring someone else’s mess, as you can adhere to the same interface and not risk breaking some important business function. In other cases, it is better to intercept.

Interception

A pattern which lends itself to this is called Proxy, and if you spend any time with Google and search terms like “c# proxy pattern” you’ll quickly end up finding a lot of information about implementing it. You’ll also find interesting stuff about Castle.DynamicProxy, and you may quickly realise this is an excellent way of adding the ability to dynamically intercept a method to add additional functionality on the fly. I’ve implemented an interceptor in the Github API library, with the core magic being:

public void Intercept(IInvocation invocation)
{
    invocation.Proceed(); // let the RestClient be instantiated as normal.
    var restClient = (RestClient)invocation.ReturnValue;
    restClient.Authenticator = _authenticator; // add the authenticator
    invocation.ReturnValue = restClient;
 }

I then wrap the interception up in a static class, which is a technique I saw on another website, which I then wrap in a extension method which with a little bit of generics hangs off API classes in a fluent manner.

var api = new UserApi(GitHubUrl).WithAuthentication(authenticator);

I feel like it is the best way to do this sort of thing, and I will certainly starting using more of it, where necessary, in all my projects.

var a = new UserApi();
var user = a.WithAuthentication(authenticationObject).GetUser("example");
var b = new UserApi().WithAuthentication(authenticationObject);
user = b.GetUser("example");

Thus making it possible to instantiate an API object without having to authenticate, then when authorization for an action is required, the authentication can be provided. When that actually happens is, I think , something that is an implementation detail best left to future consumers of the library. Assuming I get it finished.

I got bogged down over the course of several months in trying to wrap my head around a clean way of implementing this. Initially I had a good inheritance from an Api base class to the UserApi class – this is sensible, the base Api class does after all contain methods which are going to be common to different classes, such as GistsApi, RepositoriesApi etc.

Then things got a little screwy.

At that point I had the following implemented:

var github = new Github(authenticator);
var user = gitHub.User.GetUser("example");
user.Authenticated.AddEmail("example@example.com");

Which doesn’t seem all that bad. The User property on the Github object was an instance of UserApi. When the example User is fetched, the UserApi object was added an internal instance on the User object. Then the Authenticated property on the User object returned a new AuthenticatedUser, which acted as a wrapper to the internal UserApi instance where the actual AddEmail was hidden as internal.

Needless to say, I knew something was wrong with that, and I spent far too long in coming up with a more elegant solution.

In my second stab at things, I tried to implement Decorator to solve this problem, that is, decorate the UserApi with the additional functionality to add the authentication. The trouble is that the way I wanted to implement the pattern wouldn’t have lent itself exceedingly well to having specific functionality for the different parts of the api.

Then I thought to myself, wouldn’t it be great if I could intercept the method in the base class which gets the RestClient and add the authentication to it on the fly. A little Googling taught me that this is idealised as the Proxy pattern, from which it was but a short leap to the Castle project and DynamicProxy.

To recap this particular project, you may like to browse some of the earlier posts on it, wherein I grandly proclaim my intent to write a “Github API in C#”. Which I should really have finished by now. As you will have no doubt realised, I do suffer from a certain amount of laziness. That is a subject for another blog post. To my shame, I can tell you that the amount of Github’s REST API which I’m covering is minimal, limited to a subset of the available User related commands.

Moving swiftly along, with no trace of irony.

In the months since the start of this project, Github has release v3 of their REST API, which contains many updated and/or new methods to access the whole plethora of the functionality available on Github. Indeed, they have even gone as far as to release a desktop client for Mac’s, and for all I know are working on a Windows version, which would then render this effort of mine (because that’s what I’ve always intended) redundant.

So, despite not blogging about it, and despite going months between commits, I have been working on the library. The RestSharp git sub-module is gone (I mean, who likes sub-modules anyway?) in favour of the NuGet package. The authentication has been reworked slightly (still no OAuth yet) and the API is a little more fluenty.

Of course, it still doesn’t actually let you do very much, I mean even after a year, you still can’t perform all of the actions available to a user. This is terrible, and speaks volumes about me, as a person. Procrastination is my enemy.

Why?

It is simple, really: A large percentage of the programmers I have met,  have worked with or follow on Twitter absolutely love to write code, whether it is for a website, a desktop application of some kind or they are just monkeying around with something. They love it! I love doing it. A number of my friends love doing it. And the best thing?

We get paid to do it!

Don’t get me wrong here, I know plenty of people who turn up at 9am and go home at 5pm and wouldn’t even consider writing anything for themselves or doing any open source work. For them, it’s like a factory job, albeit a (generally) much better paid one. Jeff Atwood (love him or loathe him) has a great post about these sorts of programmers titled “There are Two Types of Programmers”. Even though these programmers might not code in their spare time, I’d still say that 99% still like their job.

I’ll place myself firmly in that 20% block of programmers though. I wouldn’t say I was a rock star programmer, I’m certainly not bad, but I do always want to constantly improve myself and my ability. As the old saying, “Practice makes perfect”. I definitely love my job. Maybe I could do without some of the meetings and the office politics which comes from working in a large company, but still, I love what I do.

I get paid to do what I love doing; I consider myself lucky.

try
{
/* code */
}
catch(Exception)
{
}

I see it in several different languages almost daily. It really frustrates me that my colleagues and predecessors did this. I stamp it out ruthlessly.

Here is a great post on why empty catch blocks are bad. Here is a great question and series of answers on StackOverflow about best practices for exception handling.

Oh crap, complicated string parsing…

RestSharp to the rescue! We don’t have to worry about parsing the response content, because RestSharp can do it for us.

What we need to do, is model the response content into a POCO (Plain Old Clr Object):

public class User
{
	public virtual int Id { get; set; }
	public virtual string Login { get; set; }
	public virtual string Name { get; set;}

	...
}

Note that in this User class, I’ve made the properties virtual, this is not necessary for RestSharp to function correctly, it’s more habit on my part from working with NHibernate; however it does mean you can reuse the same models with NHibernate (if you wanted to do something like store the response in a database, for example).

Then we need to modify our client such that when we execute the request, we instruct RestSharp to construct an instance of the User object. Create the client in the usual way and also create the request in the usual way. The magic is in how the client executes the request:

var request = new RestRequest
				  {
					  Resource = string.Format("/user/show/{0}", username),
					  RootElement = "user"
				  };

var response = client.Execute<User>(request);

var user = response.Data;

As you can see, the Execute method has a generic overload. Internally, RestSharp detects that because we have used this overload, we want to deserialise the response content into an object of the given type, and it performs the deserialisation and constructs an instance of the object. The way that it does this is by looking at the Content-Type header in the response, and it uses the correct deserialiser depending upon the Content-Type. You can see more detail about this on RestSharp’s Github project pages.

It is really easy to work with the response from your REST request with RestSharp, you can access the raw string content of the response, or deserialise it into a POCO – it’s up to you.

Github has a REST base API, the details of which are available at develop.github.com. Before continuing, I should point out that there is an existing C# library already available, if you want to use that.

We’ll leverage John Sheehan’s excellent RestSharp library to do most of the heavy lifting.

Before we can really do anything, the first task at hand is to learn how to work with RestSharp, and how we can make a request and receive a response. Fortunately, RestSharp makes it really easy, and there are excellent resources on the project’s wiki page which explain how to do things. Let’s see a quick example:

[Test]
public void MakeBasicRequestToTwitterWithRestSharp()
{
	var client = new RestClient("http://api.twitter.com");
	client.UserAgent = "TemporalCohesion.TwitterApi";

	var request = new RestRequest();
	request.Resource = "statuses/public_timeline.json";

	var response = client.Execute(request);

	if (response.StatusCode == HttpStatusCode.OK)
	{
		String content = response.Content;

		Assert.That(content, Is.Not.Null);
	}
	else
	{
		Assert.Fail(response.StatusDescription);
	}
}

Here we are making an authenticated request to Twitter, asking for the public timeline in JSON format, but, the same code can easily be applied to github.com. We’ll see more of that later. First we create the client object, and then create the request object – telling it what resource to actually request, and then we execute the request using the client, and then do something with the response. Pretty straightforward, huh?

There is quite a lot that we can do with the Github API at this point, although you’ll quickly see that to do anything really interesting (i.e. modifying your github account, or creating/forking repo’s) requires you to be authenticated. Fortunately for us, Github uses HTTP Basic Authentication, and, RestSharp has a HttpBasicAuthenticator class, and if you put the two together, you can make an authenticated request to Github like this:

var client = new RestClient
				 {
					 BaseUrl = "https://github.com/api/v2/json",
					 Authenticator = new HttpBasicAuthenticator("test", "test")
				 };

After we set the authenticator, RestSharp takes care of making sure that the headers of the requests we make to Github’s API contain the necessary authentication which identifies us to Github. You’ll note that the BaseUrl here is set to https://github.com/…, so that we can take advantage of SSL. You can can access public data via normal http://, but if we are going to do anything that requires authentication, it will be best if we choose to use https://

Github also provide us with an API key. This is a unique key which identifies us to Github, and give our requests a little bit more security. We can’t set this key with RestSharp, as we need to modify the way the authorization header is generated when we make a request. What we can do though, is to implement our own IAuthenticator to do handle it for us. You can see my implementation up on Github. It’s fairly straightforward – I still wanted to allow basic username:password authentication, as well as username/token: authentication for Github.com. Let’s create a unit test to check everything is working OK.

How do we know if we have made an authenticated request successfully? If you make a request to Github for a user, and you are authenticated as that user, then as well as the standard user response, there is some additional information included in the responses that only you, as the authenticated user, can see. And we can check for this information in the response:

[Test]
public void MakeAuthenticatedRequest()
{
	var restRequest = new RestRequest
            {
                Resource = "/user/show/sgrassie"
            };

	var client = new RestClient
					 {
						 BaseUrl = "http://github.com/api/v2/json",
						 Authenticator = new GitHubAuthenticator(_secretsHandler.Username, _secretsHandler.Password, true)
					 };

	var response = client.Execute(restRequest);

	Assert.That(response.Content, Is.StringContaining("total_private_repo_count"));
}

The unit test is pretty straightforward, I make a request object which will get my user account, I authenticate the request and then execute it. Then I can simply check that the response content contains “total_private_repo_count” – this would only be returned if the request was an authenticated request.

One thing you might notice in the test is that in the GitHubAuthenticator constructor, I get my username and password/api token from the _secretsHandler object, an instance of a class I’ve written which will load my username, password and api key from an XML file. This is so that I don’t have to put my Github.com password and API key into the project’s Github repo, because that would be bad.

Here is my take it. I’m putting it here so I can find easily find it again. Basically it’s the same, but I’m using a lambda to create my anonymous delegate:

[Test]
public void UnitTestNodeChanged()
{
 var receivedEvents = new List<XmlNodeChangedEventArgs>();
 var document = new XmlDocument();

 document.NodeChanged += ((sender, e) => receivedEvents.Add(e));
 document.Load("C:\file.xml");

 Assert.That(receivedEvents.Count, Is.EqualTo(1));
}

Nice and short, and to the point. We can test the fact that the event was raised (or not); how many times the event was raised; and, we can test the event arguments.

I like it. Some people may not, but it suits my purposes.