Step by Step Guide to Building a Things API Integration in C#

Aug 13, 2024 • 8 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your productivity with the Things API? In this guide, we'll walk through building a robust C# integration that'll have you managing tasks like a pro. Let's dive in and make some magic happen!

Prerequisites

Before we start coding, make sure you've got these essentials:

Visual Studio or your favorite C# IDE
.NET Core SDK (latest version)
A Things Cloud account (duh!)
API credentials (we'll cover this in a sec)

Setting up the project

First things first, let's get our project off the ground:

Fire up Visual Studio and create a new C# Console Application.
Name it something cool like "ThingsAPIIntegration" (or whatever floats your boat).
Once your project is ready, it's NuGet time! Install these packages:
- Newtonsoft.Json (because who doesn't love easy JSON handling?)
- RestSharp (for smooth API requests)

Authenticating with the Things API

Alright, security first! Things API uses OAuth 2.0, so let's set that up:

using RestSharp;
using Newtonsoft.Json.Linq;

public class ThingsAuthenticator
{
    private const string TokenUrl = "https://cloud.culturedcode.com/oauth/token";
    
    public string GetAccessToken(string clientId, string clientSecret)
    {
        var client = new RestClient(TokenUrl);
        var request = new RestRequest(Method.POST);
        request.AddParameter("grant_type", "client_credentials");
        request.AddParameter("client_id", clientId);
        request.AddParameter("client_secret", clientSecret);

        var response = client.Execute(request);
        var json = JObject.Parse(response.Content);
        return json["access_token"].ToString();
    }
}

Making API requests

Now that we're authenticated, let's create a base client for our API calls:

public class ThingsApiClient
{
    private readonly RestClient _client;
    private readonly string _accessToken;

    public ThingsApiClient(string accessToken)
    {
        _client = new RestClient("https://cloud.culturedcode.com/api/1/");
        _accessToken = accessToken;
    }

    public IRestResponse Execute(RestRequest request)
    {
        request.AddHeader("Authorization", $"Bearer {_accessToken}");
        return _client.Execute(request);
    }
}

Implementing core Things API endpoints

Time to get our hands dirty with some real API action:

public class ThingsApi
{
    private readonly ThingsApiClient _client;

    public ThingsApi(string accessToken)
    {
        _client = new ThingsApiClient(accessToken);
    }

    public JArray GetTasks()
    {
        var request = new RestRequest("tasks", Method.GET);
        var response = _client.Execute(request);
        return JArray.Parse(response.Content);
    }

    public JObject CreateTask(string title, string notes = null)
    {
        var request = new RestRequest("tasks", Method.POST);
        request.AddJsonBody(new { title, notes });
        var response = _client.Execute(request);
        return JObject.Parse(response.Content);
    }

    // Add more methods for updating and deleting tasks
}

Handling API responses

Let's make sure we're handling those responses like pros:

public class ApiResponse<T>
{
    public bool Success { get; set; }
    public T Data { get; set; }
    public string ErrorMessage { get; set; }

    public static ApiResponse<T> FromJson(string json)
    {
        try
        {
            var jObject = JObject.Parse(json);
            return new ApiResponse<T>
            {
                Success = true,
                Data = jObject.ToObject<T>()
            };
        }
        catch (Exception ex)
        {
            return new ApiResponse<T>
            {
                Success = false,
                ErrorMessage = ex.Message
            };
        }
    }
}

Implementing advanced features

Want to level up? Let's add support for tags and projects:

public JArray GetTags()
{
    var request = new RestRequest("tags", Method.GET);
    var response = _client.Execute(request);
    return JArray.Parse(response.Content);
}

public JObject CreateProject(string title, string area = null)
{
    var request = new RestRequest("projects", Method.POST);
    request.AddJsonBody(new { title, area });
    var response = _client.Execute(request);
    return JObject.Parse(response.Content);
}

Optimizing the integration

To keep things smooth and efficient, let's add some basic caching:

public class CachedThingsApi : ThingsApi
{
    private readonly Dictionary<string, object> _cache = new Dictionary<string, object>();
    private readonly TimeSpan _cacheExpiration = TimeSpan.FromMinutes(5);

    public CachedThingsApi(string accessToken) : base(accessToken) { }

    public new JArray GetTasks()
    {
        return GetCachedOrFetch("tasks", base.GetTasks);
    }

    private T GetCachedOrFetch<T>(string key, Func<T> fetchFunc)
    {
        if (_cache.TryGetValue(key, out var cachedValue) && cachedValue is CacheItem<T> item && !item.IsExpired)
        {
            return item.Value;
        }

        var value = fetchFunc();
        _cache[key] = new CacheItem<T>(value, _cacheExpiration);
        return value;
    }
}

private class CacheItem<T>
{
    public T Value { get; }
    public DateTime Expiration { get; }
    public bool IsExpired => DateTime.Now > Expiration;

    public CacheItem(T value, TimeSpan expiration)
    {
        Value = value;
        Expiration = DateTime.Now.Add(expiration);
    }
}

Testing the integration

Don't forget to test your awesome new integration:

[TestClass]
public class ThingsApiTests
{
    private ThingsApi _api;

    [TestInitialize]
    public void Setup()
    {
        var authenticator = new ThingsAuthenticator();
        var accessToken = authenticator.GetAccessToken("your_client_id", "your_client_secret");
        _api = new ThingsApi(accessToken);
    }

    [TestMethod]
    public void TestCreateAndGetTask()
    {
        var newTask = _api.CreateTask("Test Task", "This is a test task");
        Assert.IsNotNull(newTask["id"]);

        var tasks = _api.GetTasks();
        Assert.IsTrue(tasks.Any(t => t["id"].ToString() == newTask["id"].ToString()));
    }
}

Conclusion

And there you have it! You've just built a rock-solid Things API integration in C#. With this foundation, you can expand and customize to your heart's content. Remember, the key to a great integration is continuous improvement, so keep exploring and refining your code.

Additional resources

Want to dive deeper? Check out these awesome resources:

Now go forth and conquer those tasks like the coding champion you are! Happy integrating!