Over a million developers have joined DZone.

Writing a Documented API for Your Product With ASP.NET Web API

DZone 's Guide to

Writing a Documented API for Your Product With ASP.NET Web API

Making an API is cool, but if nobody can use it, what's the point? Read on to learn how to craft comprehensive API documentation while developing your API.

· Integration Zone ·
Free Resource

Every once in a while you will be in a position to solve the challenge of writing and maintaining a piece of 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 heck 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 expand over different software systems. Today, the most used software systems are not the ones that are offering plenty of functionalities, but, rather, the ones that offer APIs 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 out 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 are you going to allow through the API?
  2. What kind of data are you going to share?
  3. How is the API going to be accessed and by whom (security, authentication, and authorization)?
  4. Limiting the API requests, a.k.a. rate limits.
  5. Choosing the 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 are you going to allow through the API?
  • What kind of data are you going to share?
  • How is the API going to be accessed and by whom (security, authentication, and authorization)?
  • Tools to document and maintain the API documentation.
  • Managing and maintaining integration examples.

Let’s get our hands dirty.

2. Writing an API Endpoint

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


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 Are You 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 a 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 the Auth Key and Secret. To be able to authenticate the call, implement the Application_AuthenticationRequest method in Global.asax.cs.


Img 4: Caller authentication from headers

All requests 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 to your exposed API methods

3. Tools to Document and Maintain Your API Documentation

At the moment, there is a huge amount of support and community activity around Swagger – the framework of API development tools for the Open API Specification. Luckily for us, as we're working in C#, it is supported in the .NET ecosystem via the NuGet package Swashbuckle. Installing this package in your web application will add support for Swagger 2.0. After 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 detail about generating the open specification for your API. Once this is complete, 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. A great thing about this 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 the 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 having good API documentation. Swashbuckle offers a 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 refreshing the page:


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 explaining how to use the API in .NET, PHP, Go, Ruby, Python, etc.

In order to cut down the time spent on support, there are some activities that you can do beforehand:

  • Create a Postman collection.
  • Create cURL.
  • Embed 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's 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 of writing and managing client libraries in different programming languages and help you 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 making sure you haven’t broken your existing client’s integrations.

integration ,web api ,api development ,api documentation ,swagger

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}