Writing a documented API for your product with ASP.NET Web API

Every once in a while you will be in a position to solve the challenge of writing and maintaining a professional technical documentation for your product REST API. Building an API is easy, right? Technically speaking it is. The biggest challenge comes when someone has to use your API for the first time. It is then, when you figure out that no-one except for the development team understands what the hack is going on behind the scenes. To avoid this potential pitfall, I would like to share our personal experience with our product’s API for sending invoices – Envoice.

​1. Planning

Businesses today have complex business processes which expands over different software systems. Today most used software systems are not the ones that are offering plenty of functionalities, but rather the ones that offer API and out of the box integrations with other popular services. Having said that, if you are planning your next venture or already developing a product you will need to spend some time to get the things sorted and allow your customers to integrate your service as part of their eco-system. There are several aspects you need to consider when preparing for API development including:

1. What kind of actions you are going to allow through the API?
2. What kind of data you are going to share?
3. How the API is going to be accessed and by whom (security, authentication and authorization)?
4. Limiting the API requests AKA – Rate limits;
5. Choosing a proper versioning strategy for down compatibility;
6. Tools to document and maintain the API documentation;
7. Managing and maintaining integration examples;

Today we are going to cover the following aspects:

• What kind of actions you are going to allow through the API?
• What kind of data you are going to share?
• How the API is going to be accessed and by whom (security, authentication and authorization)?
• Tools to document and maintain the API documentation;
• Managing and maintaining the integration examples;

Let’s get our hands dirty.

​2. Writing an API endpoint

Since you are reading this post I would assume that you’ve already created a Web API 2.0 Controller as in the example bellow:

Img 1: Example of an API method

We have an endpoint that describes the process associated with the “Client” domain entities. We’ve decided that we would like to enable the developers to programmatically:

• List all of the clients associated with the authorized account;
• Create a new client;
• Update an existing client;
• Delete an existing client;
• Check if an existing client can be deleted;
• Return the details for the requesting client;

​2.1 What kind of actions you are going to allow through the API?

First things first, we need to decide what type of data we are going to process and return back to the consumer. Ex: Mapping client details data call Client API:

Img 2: Mapping a domain entity to a DTO

In our example we have a custom DTO that we are going to use as a response when retrieving details about the client.

​2.2 Securing the endpoint

Besides setting up a RequireSsl attribute, we need to make sure that we can identify the caller when accessing the API. Let’s say we need to secure the process of creating a new client.

Img 3: Securing an API method

A simple yet effective approach would be to use “API Auth Key” and “API Auth Secret”. With RNGCryptoServiceProvider we can create an Auth Key and Secret and associate them with the user’s account. Make sure they can be regenerated. Note: Recommended key length would be 128 for both Auth Key and Secret. To be able to authenticate the call, implement Application_AuthenticationRequest method in Global.asax.cs.

Img 4: Caller authentication from headers

All request that require authentication should contain an Auth Key and Secret headers.

Img 5: Extracting auth key and secret from the request headers

If the key and secret are valid, we will allow the request to be executed. This verification can be achieved with a custom authorize attribute.

Img 6: Web API custom authorize attribute that can be applied on your exposed API methods

​3. Tools to document and maintain the API documentation

At the moment there is a huge support and community activity around Swagger – framework of API development tools for the Open API Specification. In our favour, it is supported in the .NET eco system via the NuGet package: Swashbuckle. Installing this package in your Web application, will add support for Swagger 2.0. After the installation you will find a newly generated Swagger configuration file under App_Start\SwaggerConfig.cs.

Img 7: Sample Swashbuckle configuration for Swagger

The configuring is extensive and allows you to go into details on generating the open specification for you API. Once done, you can check the results on your predefined API documentation route. The generated API specification will contain all of the exposed Web API methods together with the associated comments and DTOs. The associated comments are going to be read from the XML comments from the output directory. Usually that is Project.Namespace.XML.

​3.1 Configuration extension

Since the requirements may vary, you might end up needing a functionality which is not supported out of the box. Great thing is that you will be able to write extensions and override the process of creating the API specification. In case you need to extend, you can write the following types of extensions: – Operation filters – override the specification on an operation level. Ex: Create a new client action; – Schema filters – override the specification schema. Ex: exclude a property from the request/response; – Document filters – override the document. Highest in hierarchy. Ex: Set all operations to lowercase; There are many useful examples that can be found on Swashbuckle for Document, Schema and Operation filters. Make sure you check them before rolling out on your own.

​3.2 Generating a usable UI/UX for your API specification

I understand that developers are not always happy when it comes to creating a usable UI/UX, but it is a prerequisite to have good API documentation. Swashbuckle offers an UI out of the box, but it is poorly designed and renders raw information from the API specification. There is one library that comes to the rescue: REDOC. Redoc lets you generate a modern UI by simply providing the library with the absolute URL to the API specification.

Img 8: Redoc configuration

You should get the following result after refresh:

Img 9: Example of an API documentation generated by Redoc

​3.3 When documentation is not enough

Often after releasing the API, you will face the hard truth, that the developers who are integrating your API with some existing product out there will need help to understand what your API does and how they can use it in their programming language. This can decrease your team productivity time, as you will spend countless hours into explaining how to use the API in .NET, PHP, Go, Ruby, Python. In order to cut down the time spent on support, there are some activities that you can do beforehand: – Creating a Postman collection; – Creating cURL examples on GitHub; – Embedding the Postman collection and GitHub examples as part of your API docs; Postman allows you to create an environment from which anyone who is interested in your API can utilize it to execute requests, explore the API capabilities and export the examples in their preferred programming language.

Img 10: Postman code generation for an API call

​Having this, will save you from the trouble to write and manage client libraries in different programming languages and to reduce the learning curve for your custom libraries.

​4. Wrapping up

​While you keep developing your API don’t forget that your documentation will be updated automatically but you will still need to update your Postman docs and GitHub examples. While iterating, reserve some time for maintaining the documentation and analyze you haven’t broken your existing client’s integrations.