Why Azure Rest APIs and How to Prepare for Using Them?

DZone's Guide to

Why Azure Rest APIs and How to Prepare for Using Them?

MS's Azure comes prepped with plenty of integrations and methods, but which should you choose? RESTful services are all the rage, but how do they work with Azure? Read on to find out from DZone MVB Gunnar Peipman.

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

It’s good if service comes out with public REST API. It doesn’t matter what platform we are on or what flavor 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 a 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 always this way.

REST APIs in Application Architecture

REST APIs are usually pretty simple as they are stateless and doesn’t expect us to take care of complex state handling. We make a request to the service and get a response to our request. A response can be a success or failure. We must also be ready for unexpected cases like network problems or service failures.

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

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

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

As we don’t want to expose the specifics of the REST client to our application, we usually have some adapter class or service that the application uses to communicate with an external service. An adapter class or service accepts arguments of types that are known in the application domain and also return values are of known types in the 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 an abstract level. Every API usually has its own specifics and complex parts but it doesn’t matter to us right now because we won’t dig deep into the details during this blog post.

Building Simple REST Client Base

REST APIs usually use JSON as a data exchange format. In the heart of our REST client, there must, therefore, be an HTTP client with some powerful JSON library like Newtonsoft.Json. This library provides us also with JSON serialization and deserialization.

Now let’s build a 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.

It’s a simple and primitive class, but we can build our specific REST clients on it. The next blog post will show you how to use this base class when building a 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 APIs until libraries come 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 a couple of different calls to service then using a simple custom REST client may save us some megabytes in application size.