4 Key Factors to Consider when Developing Applications with Web API

By Denise Wang| February 09, 2018

Building a REST API is a great way to write reusable code that can be consumed using many different technologies. However, deciding which technology to use when building your REST API application can be a complicated decision.

While Web API is a lightweight and simple-to-use solution that has proven to be a popular choice for many developers, there are still many factors to consider. How do you know it’s the right choice for your specific project requirements? Will the end-product meet your needs?

To help avoid potential rework or complications down the road, leading to more time and money spent reworking the solution, we’ve gathered a list of key factors and resources to consider when using Web API.


Web API has multiple route attributes that allow you to set custom routes, as well as a default convention-based system. Logical routing will help keep the API intuitive to use. Microsoft’s best practices for API design is an excellent resource to help you build a well-designed web API.


Versioning will help you make changes to your API over time while avoiding breaking existing functionality. Web API does not support versioning out of the box, but Microsoft has created a NuGet library to handle this. Using this library, you can apply versions to individual controllers to reduce duplicate code in your application.

Error handling

The error information you return to your API users should help them understand what went wrong and how to resolve the issue. Web API does not implement any standard error handling procedure, but we recommend these best practices:

  • Use one error class throughout the API - this provides a consistent user experience and reduces duplicate code
  • Return a descriptive HTTP status code

Make sure the error includes a message that helps the user resolve the issue.


Using a tool to generate your documentation can save you time and even help streamline testing. Swashbuckle is a library for Web API that generates documentation using the Swagger framework. It will automatically provide your Web API application with a user-friendly documentation page, and you can even set it up to use the comments from your code as help text.

Another benefit of Swashbuckle is that the documentation it provides can be imported for testing tools such as SoapUI. This can help you save time when testing. For more information on Swagger, check out the Swagger website.


Tech Insights Report