Why Azure REST API-s and how to prepare for using them?

When new Microsoft Azure services come they usually have REST API-s available. Of course, there are usually client libraries available too as NuGet packages but usually not for every .NET flavour. Although Microsoft has plans to publish libraries for CoreCLR too it doesn’t happen always fast. Let’s see how REST API-s work and how to prepare for using them.

It’s good if service comes out with public REST API. It doesn’t matter on what platform we are or what flavour of .NET Framework we are using – we can start consuming new services right now.

I know, it’s annoying for many developers if we don’t have well designed API client library for service. Sometimes it makes us think that the service is not ready yet or at least it’s closer to beta than to GA release. But it’s not this way always.

REST API-s in application architecture

REST API-s are usually pretty simple ones as they are stateless and doesn’t expect us to take care of complex state handling. We make request to service and get response to our request. Response can be success or fail. We must also be ready for unexpected cases like network problems or service failures.

Now let’s try to draw out architecture of REST API-s step by step to understand things better.

Rest client is used by some classes in application. These classes create instance of REST client and then call some method on it. When REST client method is called the method translates input to HTTP request and sends request to REST API end-point. Response from end-point comes as HTTP response and REST client translates it to return value of some type.

If we dig deeper then we see that input for REST client method is not always just some simple class. Often there is class that defines some common parameters for API call and objects on what operations are performed are given as property or collection of this class. Same holds true for responses.

As we don’t want to expose specifics of REST client to our application we usually have some adapter class or service that application uses to communicate with external service. Adapter class or service accepts arguments of types that are known in application domain and also return values are of known types in application domain. This means we use some object-to-object mapping between domain and REST client types in adapter or service.

This is the big picture at abstract level. Every API has usually its own specifics and complex parts but it doesn’t matter us right now because we don’t dig deep to details during this blog post.

Building simple REST client base

REST API-s usually use JSON as data exchange format. In the heart of our REST client must therefore be HTTP client with some powerful JSON library like Newtonsoft.JsonNewtonsoft.Json. This library provides us also with JSON serialization and deserialization.

Now let’s build simple base class for our REST clients.This base class provides us with simple methods to move data between our application and some Azure service.

public abstract class RestClientBase

{

    public virtual void AddHeaders(HttpRequestHeaders headers)

    {

    }

    protected async Task<T> Download<T>(string url)

    {

        return await Download<T>(url, HttpMethod.Get, null);

    }

    protected async Task<T> Download<T>(string url, HttpMethod method, string body)

    {

        using (var client = new HttpClient())

        {

            var request = new HttpRequestMessage();

            request.RequestUri = new Uri(url);

            request.Method = method;

            if (!string.IsNullOrEmpty(body))

            {

                request.Content = new StringContent(body, Encoding.UTF8, "application/json");

            }

            AddHeaders(request.Headers);

            var response = await client.SendAsync(request);

            if (response.Content == null)

                return default(T);

            var stream = response.Content as StreamContent;

            var responseBody = await stream.ReadAsStringAsync();

            var result = JObject.Parse(responseBody).ToObject<T>();

            return result;

        }

    }

}

It’s simple and primitive class but we can build our specific REST clients on it. Next blog post will show you how to use this base class when building simple REST client for Azure Search.

Wrapping up

Although ready-made libraries for Azure services are more convenient to use than plain naked REST API end-points we can always go with REST API-s until libraries are coming to the platform we are working on. As REST is architecturally simple it’s easy to build custom REST clients. If our application uses only couple of different calls to service then using simple custom REST client may save us some megabytes in application size.