The Old-Fashioned Way

If you have worked with REST APIs in C# before, this code should look pretty familiar. We just create an instance of the HttpClient and use it to implement all of our needed requests. For basic apps, the is fine. You can probably come up with some optimizations to reduce your amount of duplicated code and handle errors in a graceful way.

However, there is a lot of boilerplate code in here. You can imagine, that if you have a dozen or more calls to implement, there are a lot of pretty similar lines of code to be found in your API client class. They will all serialize or deserialize an object and send some request. This can be done in a better way.

HTTP Requests with Refit

One way to overcome the redundant code from the “old-fashioned” way, is by using a library called Refit. With Refit, you can reduce your code needed to communicate to the backend to a simple interface. In that interface you decorate the method signatures with a couple of attributes, and the rest will be generated for you at compile-time. Let’s see how this works.

From this interface, the full implementation will be generated at compile-time. It won’t be exactly like the code in Listing 4-1, but it will look pretty similar. To be clear: this code lives in your client application, inside your app. Refit generates code from your interface definition to communicate with your backend. This saves you the trouble of writing (de)serialization or HTTP call code over and over again.

For each method signature, you can see I have adorned it with an attribute. The name of the attribute indicates what HTTP verb is to be used for that request. In the code of Listing 4-2 there are two methods: one uses the GET verb and one uses the POST verb. Of course, the other verbs are available as well.

As a parameter for the Get and Post attributes, you need to supply the relative endpoint at the backend. Later, we will provide a base URL for the client.

Something cool is going on in the endpoint definition of the GetPersonById method . As you can see the “id” part of our endpoint is enclosed in curly brackets. The parameter of the method signature of the GetPersonById, is also named “id”. By constructing the attribute this way, the value we supply to the id parameter will automatically be mapped onto the values between curly brackets in the endpoint with the same name.

When working with REST, it is a very common thing to retrieve an object by its ID. This ID is of course dynamic, which would cause a problem if we have to specify the endpoints on beforehand. By using this method with the curly brackets, we overcome this problem.

Another curious thing is going on with the AddPerson method. You can see a [Body] attribute inside of the parameter list. Depending on the HTTP verb, this means that the value will be read, or will be provided in the body of the request. Since we are doing a POST request in this example, the serialized object will be put in the body because of the [Body] attribute that is in front of it.

As a parameter for the [Header] attribute you supply the key of the header; the parameter that comes after it will be used as the value.

Of course, HTTP and REST have a lot more options that you can use. Think of query string parameters and file uploads for instance. This is all possible with Refit as well, and I encourage you to check it out yourself.

To retrieve a client for this, we can simply call: RestService.For<IBackendService>("https://www.example.com");. With the client we get out of this line of code, we can call the methods that we have defined in the interface for it. You probably want to wrap this into some kind of client of your own to handle errors, etc.

Probably a good thing to know is that when a call from Refit is not a HTTP success status code, so whenever a call is not a HTTP 200 OK, it will throw an exception. That in itself might be a reason to wrap it into a class and not repeat a lot of error handling code in your view models.

Other Libraries

There are, of course, other libraries out there that will help you with making HTTP requests. One of them is called RestSharp . This library, and others out there, of course have its own use but are not so extensive as Refit. Or at least extensive in its own way. RestSharp does not generate implementations for you; it just provides you with shorthand methods for HTTP calls. It will also take care of the serialization and deserialization for you. So, if you don’t like to give out control on what your methods look like down to the letter, libraries like RestSharp might be better for you.

Akavache

The Akavache library , originally by Paul Betts, is based on SQLite3 and provides us with an asynchronous and persistent key/value store. It is extremely suitable for expiring caching data but can also be used to save user settings or other data.

I have been using this plugin in a number of my projects because it just works and it is such an addition to the user experience. Before I knew Akavache, I just had users look at an empty list view that may or may not had a loading indicator. While it is functional, it might not be what users expect nowadays. If you look at other popular apps by big vendors, you will see that you are presented with data immediately and data is then loaded and replaced for you as you go. This makes for a much better experience for your users.

Installing Akavache is easy and happens through a NuGet package. Go to the screen to add a NuGet package to your project and find the akavache and akavache.sqlite3 packages. Add these to your shared project as well as all your platform projects. Failing to do so might result in using only the in-memory store, which is reset with every app start. Or your app might not work at all. Figure 4-3 shows the required packages being added in Visual Studio for Mac.

To show you how to use Akavache in code, let’s stick with the people example from the “Connecting with REST APIs” section. For this example, we will retrieve a list of all people. Assume that we have implemented the REST client with Refit and hold an instance in the _restService variable.

There is a couple of things that stand out in this piece of code. Let’s go through it from top to bottom. First, notice that we now return an IObservable object. Objects that implement the IObservable interface can send push-based notifications to subscribers.

There is another parameter that specifies an absolute point in time when the cache is expired as an addition to the expiration logic you might have in the third parameter.

In the expiration logic you can also see I incorporated the Connectivity plugin to first determine if we have a connection. If there is no connection available, we will just work with cached data.

Imagine that this code lives in a view model and we have a variable _backendService that holds an instance to the class that retrieves our people. Because the GetPeople returns an IObservable, we can use the Subscribe on it.

The Subscribe method takes in a function with an input parameter of the type that we specified on GetPeople, in this case a collection of Person. When this method gets invoked, we clear People, which is a more global collection and start repopulating this collection. Probably because we are showing in in some kind of list in the UI.

If we only get cached data, we pass through here once and it will be lightning fast because we are loading data from this. When there is data in the cache, this will happen either way. So, the user is presented with the dataset that is already in there. When the cache is expired and we are able to retrieve new data from remote, we will pass through this method again, but now with new data. Because of the way the OS handles the UI updates, the user will barely notice that new data is coming in. And of course, you could make the updating of data a bit smarter than just replacing the whole thing.

The Subscribe method returns an IDisposable object. To avoid memory leaks, make sure that you dispose the observable whenever you do not need it anymore. You can do this by capturing the return value of the subscribe method in a variable like this: var subscription = _backendService.GetPeople().Subscribe(…); and then disposing it later, like this: subscription.Dispose();.

Akavache has some more methods that are more or less shorthand for caching files, images, and secure data. They should be pretty self-explanatory.

Monkey Cache

Another caching provider is Monkey Cache. This plugin is also very good but goes about things a little differently. First of all, it has different persistence providers. You can choose from SQLite, LiteDB, and FileStore or roll your own if you’re feeling adventurous.

All of these providers end up doing the same thing—persisting data—but one has some small advantages over the other, mainly in terms of performance. When you are working with small amounts of data, under about 50 records, the differences are negligible. Above that, things start to matter. Figure 4-4 shows a screenshot of the test results as published by James Montemagno (the author of this plugin) himself.

Unlike Akavache, in Monkey Cache, you do not get to choose where your data is persisted. Per platform it will get saved in a specific location. For all platforms this will be the local app’s folder.

Installing Monkey Cache is just as easy as any other plugin; you can install it through NuGet. Just find the package named MonkeyCache and install it, together with MonkeyCache.SQLite, MonkeyCache.LiteDB, or MonkeyCache.FileStore. Make sure you also install this on your shared project as well as your platform projects.

You need to initialize with just one line, where you state your application name. This can be anything you make up and will be used as a name for your caching container. Just call Barrel.ApplicationId = " YourAppName"; before you call any other caching method.

The biggest difference here is that Monkey Cache will not present the user with cached data immediately while retrieving data remotely if needed. You as the developer are responsible for how data is cached and how it is presented to the user.

You should see some familiar things in the code from Listing 4-11 by now. First, we check if there is an Internet connection. If the device is offline, we always return the cached data. If we are online, see if our cached data is still valid. If so, return that cached data. If the data has expired, we get it from remote, put it in our cache, and return the just fetched data to the user.

To make your life easier, you can of course create some generic methods for this which you can reuse. Monkey Cache also has support for ETags to reduce network traffic. What this means exactly we will learn a little down the road in this chapter.

Retry Policy

The Retry policy is pretty self-explanatory: you are able to retry a request with conditions.

This code seems a lot to take in at first, but when you see all the different pieces, it’s not so bad. Let’s go through it step-by-step. The reason why the code seems so much is because it is actually a few methods chained together. If you look closely, you will see the Handle, WaitAndRetryAsync, and ExecuteAsync methods. To make it extra confusing, all methods have parameters that take a lambda expression.

All methods originate from the static Policy class. With the Handle method, we specify which kind of exceptions we want to handle with this policy. We can implement some logic here to make it even more flexible. In this example, the retry will happen only for the ApiException class and only when the ApiException.StatusCode not is NotFound. In other words, all ApiExceptions that return anything but a 404 will be retried.

This is a really powerful thing. Think about it: a 404 Not Found is very unlikely to recover when retried. The endpoint just is not there, so retrying a couple of times would make no sense. But for instance, a 500 Internal Server Error might be resolved within a small window of time and suddenly your code works again without bothering your user with any error that occurred in the background. Depending on your own requirements, you can implement a custom condition to suit your needs.

Then the WaitAndRetryAsync method tells the policy that it needs to retry for all the exceptions that come up. With the parameters you can specify how often a retry attempt should happen—three times in this case—and how long should be between retries. Again, here you can implement your own logic. On this line—retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)—you see the logic for the example code. From the policy, we get the current retry attempt as an input parameter. With the value in there, we calculate a number of seconds to a power of two. So, each attempt will be the current attempt to the power of two: 1, 4, and 9 in our case. You could also choose to have a fixed time between retries. It is all up to you!

Optionally, you can execute your own logic whenever a retry attempt it done. In Listing 4-12, you see a line that writes something to the console, that will happen whenever an exception was cached and a retry was invoked.

In the ExecuteAsync, we write the logic that we wanted to execute in the first place. Here you will see the call through our REST client, trying to retrieve data from our backend. I have implemented another write line to the console here. If an exception happens but the code recovers, you will see something happening like that shown in Figure 4-5.

If, after the specified number of retries, the call still fails, the exception is still thrown. Take that into account. One way to do this is by using the PolicyWrap, which we will see a little bit later.

Timeout

In this code, we see again the call to our REST service to obtain the people data. This time, it is wrapped in a TimeoutAsync method. The first parameter specifies that we want to wait for at most 30 seconds. The second parameter lets us specify a method that runs just before the exception is thrown when the method runs out of time. In this case we write a message to the console. The return of the Task.CompletedTask is needed to prevent warnings, because the lambda is an async method, but I don’t await anything.

Basically, that is all there is to it. Just like with the Retry policy, you see a ExecuteAsync call, which contains the actual code we want to execute.

There are a lot more options available when working with the timeout policy. The biggest feature is the ability to implement it as a pessimistic or optimistic timeout. The default strategy is the optimistic strategy. When using the optimistic strategy, you have the ability to work with a CancellationToken. When implemented, you can allow your users to cancel the operation before the timeout hits. You can, of course, also have a programmatically implemented trigger that cancels the operation.

With the pessimistic strategy, you can implement a timeout for methods that normally don’t support it. Also, cancellation before the timeout hits is not possible. To implement either the optimistic or pessimistic timeout strategy, simply pass in the corresponding value from the TimeoutStrategy enum into the TimeoutAsync method.

PolicyWrap

In this code, variables like waitAndRetry, breaker, and fallback hold instances to the policies with the same name. Then in the Execute method, the code is inserted that you actually want to run. You need two or more policies to be able to use PolicyWrap.

When using multiple policies, the question arises how execution and errors are handled. When using the PolicyWrap, all policies act as layers. Each policy is wrapped in the next until the last one is reached which executes the actual logic from the Execute method. When reading the code, policies are wrapped from left to right. In the example from Listing 4-14, breaker executes the code and is wrapped in waitAndRetry and waitAndRetry is wrapped in fallback. When the code is executed and fails, it will execute whatever the policy prescribes and, if the policy is exhausted, it will bubble up to the policy wrapping.

As mentioned earlier, it would probably be too much to handle all the policies and their options here. I would like to invite you to try the rest of them for yourself and see what you can come up with.

Storing Sensitive Data

There are a couple of solutions for storing data in a secure way. Each platform—at least iOS, Android, and UWP—has a dedicated store for secure data. On iOS it will be saved in the keychain, for Android in the keystore, and on UWP there is the DataProtectionProvider.

Multiple plugins have implemented functionality to save data in each respective secure store in Xamarin.Forms. Akavache that we have seen earlier, is actually one of them. But since we have seen that in action already, let’s look at an alternative. The alternative plugin is one we have seen earlier as well, it’s Xamarin.Essentials!

To set up the secure storage, there is a little platform-specific setup required for iOS. You need to enable the Keychain entitlement and add a keychain access group for the application’s bundle identifier. To do this, open the Entitlements.plist file, find the keychain entitlement, and enable it. This will take care of the rest for you. Then go into your iOS project’s properties and set the Custom Entitlements to the Entitlements.plist file under iOS Bundle Signing.

Transferring Data Securely

This part is actually pretty easy: make sure you only connect with HTTPS resources. On iOS, Apple already forces you to do this by default since iOS 9. Since the world isn’t up to speed with that yet, there is a way around it, but I would discourage that. If you have control over the app as well as the backend, invest some time in installing a certificate to make the connection secure. Also, make sure to do it properly and do not bypass the validity or integrity of the certificate in any way. Android does not enforce anything of this kind (yet).

Since not too long ago, an SSL certificate was quite costly, but now with the Let’s Encrypt service you can get certificates for free and in an automated way. That means there is no reason not to implement it and secure all the things!

When not using a secure connection, your app is vulnerable to all kinds of attacks. Malicious people might be able to change the content in your app or steal data from your users. If that happens and it gets out, people will not just stop using your app and prevent other users from ever installing it, but you might even face criminal charges depending on local laws. I would say that is reason enough to do everything in your power to prevent this from happening.

If you do need to get around the requirement for secure connections for iOS, because for instance you do not have the backend in your own management, you have a couple of keys to work with in the info.plist file.

The best thing to do is add an exception for a single domain. You can exclude one (or more) domains from the secure connection requirement. Excluding just a few domains is the best thing you can do, as it leaves your app as secure as possible.

Note that when implementing the code in Listing 4-19, Apple might decline your app in the store if you do not have a good reason to disable this.

As mentioned, Android does not have any requirements for this just yet. It is unclear if Google will enforce anything like this. Nevertheless, just make sure to be as secure as possible.