ASP.NET Core 2.2 & 3 REST API #23 — Creating an API SDK with Refit

Up Next: Setting up ApiKey-Based Auth

What is an SDK? It’s a standardised way which our users to consume our API in a structured manner.

For example: We want that the fellow programmers who consume our API use properly structured OOP code:

var response = await _tweetBookApi.LoginAsync(new LoginRequest(“usrname”, “password”))

We are going to use Refit for this task. Make sure to star this amazing project on Github.

The automatic type-safe REST library for .NET Core, Xamarin and .NET. Heavily inspired by Square’s Retrofit library, Refit turns your REST API into a live interface

Create a new Project > Class Library. We will call this Tweetbook.Sdk .

We’re also going to create another project called Tweetbook.Sdk.Sample . It has really become a state of the art best practise to include some example usage scenario for your api/sdk project. A console app will do for now.

Last but not least, we are going to create another class library called Tweetbook.Contracts .

Now, why do we need the contracts as a project/package? It’s a really good idea actually to be able to share the same contracts (and therefore versioning as well) through multiple projects — not just between the API and the SDK but also between other services in order to prevent code duplication and have everything be up to date easily!

Just paste the whole V1 directory in the new contracts project. Due to duck typing we do not need to adjust any namespaces! It’s still the same and it will just work because our projects are under the same solution!

If you are using Rider, it may show some false positives regarding namespaces. Perform a clean restart and everything is going to be fixed.

The next step would be to import System.ComponentModel.Annotations into the project and maybe fix another issue through the intentions pop-up menu with just one click if you see some more errors.

First and foremost, we need our sdk project to reference our contracts project as a dependency.

We need 2 interfaces.

  • IIDentityApi
  • ITweetbookApi

We are not going to create any class implementing these interfaces. This is where Refit comes in handy. Add this dependency through NuGet and let’s get started.

It’s basically an interface that creates it’s own implementation based on some interface methods and some attributes.

I’ll show you some example right here. You can find the complete code that we are going to use on our Sdk.Examples project at Github.

The [Post] and [Body] attributes are provided by Refit. This is the only piece of code needed for this to generate our implementation. You can now see that the work we did regarding the Contracts concept pays off here as well.

Now that we’ve got some basic sdk ready to run, let’s move on to our console app to provide some example code.

In the following code snippet, we are going to demonstrate how easy it is to create an implementation of that interface and use it, along with our JWT in order to perform sample tasks.

Make sure that your Tweetbook API is running at https://localhost:5001

Here’s a debug screenshot for demonstration:

For the AuthorizationHeaderValueGetter , you need to have the [Headers(“Authorization: Bearer”)] class attribute at the ITweetbookApi interface.

  • In a real system, you need to properly connect your app’s lifecycle with a token-refresh checker, typically through request-response interceptors, in order to refresh the token. There is plenty of documentation online for that and is an easy task if you have understood the intuition behind the JWT and Refresh Tokens.

You should be able to write example code for each one of our endpoints by now, but just for reference, the full example code is available here.

Up Next: Setting up ApiKey-Based Auth

Code is available on Github and the instructional videos are located on YouTube.

Keep Coding

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store