Don’t write your Web API Client code — you’re wasting your precious time

Web APIs are heavily gaining traction in the software world, replacing the (good?) old Web Services.

Virtually every API that is born today is likely to be REST and being built using frameworks like WCF (if you’re brave enough), ASP.NET MVC WebAPI or Spring.

With this wide adoption of Web APIs, it’s important to provide the tools to make it efficient to work with these technologies. One particular case of efficiency is the ability to generate code whenever possible, in order to automate repetitive and no-brain-required tasks.

Swagger is the new WSDL

If you’re old enough to remember Web Services, you’d know that W3C came up with the Web Service Description Language — or WSDL — which provides an XML-based description of the interface of the Web Service.

WSDL is able to describe all the meta-data of a Web Service: operations, parameters, returns, complex objects, transaccional meta-data, etc.

Although painful to be read by humans, WSDL has one awesome usage: Generating client code.

Because REST APIs don’t come with such a description language, the community closed the gap and Swagger was born.

Generating C# Web API Clients with NSwag

NSwag is an open source toolbox that, among other things, is able to generate C# and TypeScript client classes to consume Web APIs.

It supports generating client code in the following scenarios:

• From ASP.NET Web API assembly by inspecting the assembly compiled by an ASP.NET Web API application or ASP.NET Core MVC;
• From Swagger specification either by reading the OpenAPI specification generated by Swagger or by generating it from the compiled assembly of the Web API;

It also allows generating Open API specifications for ASP.NET Web API projects that do not use Swagger, which enables scenarios where users don’t want or can’t use Swagger.

The documentation is very good and pretty extensive, but the following video is a good place to start:

Using NSwag on a project

My test bed for NSwag was a small project I’m preparing for a training session, where I used NSwag to generate a C# Client for a Web API.

Because the project is being built “as-we-go”, the interfaces of the Web API are subject to regular changes. So, I wanted to have simple way of re-generating the client code whenever the API contract was updated.

Here’s the steps I took:

Create a Class Library for your client code

I started by creating the Class Library that will receive the generated code and provide the client functionality.

Pro tip: Always look to follow name conventions on your solutions. In this case, I named this Class Library with the suffix .Client to ensure that the purpose of this assembly is clear.

For example, if your Web API project is named Foo.Bar.WebApi, the client assembly should be Foo.Bar.WebApi.Client.

Creating .nswag project file

Then, I had to create my web-api-client.nswag file with NSwag Studio.

NSwag Studio

This was pretty straight forward:

1. Build the Solution to ensure the Web API DLLs are compiled;
2. Select the .NET Assembly where the Web API Controllers are compiled into;
3. Select which Controllers to generate client code from;
4. On the “Outputs” pane, select the “CSharp Client” checkbox;
5. Enter the namespace for the generated classes;
6. At the end of the pane, enter the name of the file where client code will be generated — this file should in the directory of the .Client project;
7. Click “Generate Files”;

Et voila! The generated code for my beautiful Web API:

Code generated by NSwag

Then I saved the .nswag file in the .Client Class Library and put it into source control, to make sure everyone is able to generate code using the same settings.

Re-generating client code

Whenever changes are made to the API, it’s pretty simple to update the client code to reflect the new contract.

I prefer to use the command line tool for this — it’s easier to automate and more direct than using the Studio.

NSwag also ships with an MSBuild task which can be used to integrate code generation within a project’s build process.

For that, I’ve used NSwag’s package for NPM which provides command line tools to perform several tasks.

$ npm install nswag --save-dev

$ .\node_modules\.bin\nswag.cmd run web-api\WebApi.Client\webapi-client.nswag

And that’s it! Client code generated in a matter of seconds.

Output of generating code using the command line tool

Next up…

This was a very simple use case, so I’m actually eager to test NSwag on a real-world project.

There are some still things I need to explore from this point on.
The ones I’ve already identified are:

• Explore the options of NSwag Studio: there are lots of them and some look really interesting;
• Add authentication headers to the HTTP request: the generated clients have a hook named PrepareRequest that I suspect could be used for this;
• How to use HTTP Connection Pooling: by inspecting the generated code, a new HttpClient is created and disposed on each request — which I suspect (but not proved) that will create a new socket for each request. If this were to be used on a system that is subject to high load, the connections to Web APIs should be pooled to improve performance.