Monday, June 12, 2017

ServiceStack the clean way to integrate API calls

ServiceStack is a powerful and fast framework which adds value to any .NET solution. It handles a fair bit of functionality and features, as the image below shows). This post will be going over just how simple it is to integrate a REST API call into your solution using ServiceStack.

What comes out of the box with ServiceStack
In this example, I am going to be calling an API to get weather data using Open Weather Map. This API has limited free access, but does require signup to get an API key. An example of the call is shown below, it simply takes in the city along with an app ID.

The request model

You'll notice with the request model below that the call type is defined as get, the return object is referenced directly, and that DataMember is the service's variable name (which allows for cleaner classes). The route does not include any querystring as this is automatically handled, this could be something like /weather/{q/ if  a parameter is part of the route.
using ServiceStack;
using System.Runtime.Serialization;

namespace MyProject
{
    [Route("/weather", "GET")]
    [DataContract]
    public class CurrentWeatherRequestModel : IReturn<CurrentWeatherResponseModel>
    {
        [DataMember(Name = "q")]
        public string City { get; set; }

        [DataMember(Name = "appid")]
        public string ApiKey { get; set; }
    }
}

The response model

The response model is simple enough, DataMember could also be used to have a cleaner class, but this example demonstrates that ServiceStack will map directly to the model.
using System.Collections.Generic;

namespace MyProject
{
    public class CurrentWeatherResponseModel
    {
        public Coord coord { get; set; }
        public Sys sys { get; set; }
        public List<Weather> weather { get; set; }
        public Main main { get; set; }
        public Wind wind { get; set; }
        public Rain rain { get; set; }
        public Clouds clouds { get; set; }
        public int dt { get; set; }
        public int id { get; set; }
        public string name { get; set; }
        public int cod { get; set; }
    }

    public class Coord
    {
        public int lon { get; set; }
        public int lat { get; set; }
    }

    public class Sys
    {
        public string country { get; set; }
        public int sunrise { get; set; }
        public int sunset { get; set; }
    }

    public class Weather
    {
        public int id { get; set; }
        public string main { get; set; }
        public string description { get; set; }
        public string icon { get; set; }
    }

    public class Main
    {
        public double temp { get; set; }
        public int humidity { get; set; }
        public int pressure { get; set; }
        public double temp_min { get; set; }
        public double temp_max { get; set; }
    }

    public class Wind
    {
        public double speed { get; set; }
        public double deg { get; set; }
    }

    public class Rain
    {
        public int __invalid_name__3h { get; set; }
    }

    public class Clouds
    {
        public int all { get; set; }
    }
}

The call

Finally here is the actual service call, in 3 simple lines the API is called and the result is mapped back to your response class. The base URL for the API is also set here.
using ServiceStack;

namespace MyProject
{
    public static class GetCurrentWeather
    {
        public static CurrentWeatherResponseModel ByCity(CurrentWeatherRequestModel request)
        {
            var client = new JsonServiceClient("http://api.openweathermap.org/data/2.5");
            client.Headers.Add("ContentType", "application/json");

            return client.Get(request); 
        }
    }
}

Conclusion

As you can see from the example above, ServiceStack is a really clean/simple way of making service calls in your c# solutions. The code is easily readable, can be integrated into unit tests and works well across multiple environments, if the base URL is a configurable variable.

No comments:

Post a Comment