ASP.NET Web API Design: A How-To Guide

Visual Studio provides an option for web applications called ASP.NET Web API. This is a technology designed to make it easy to build HTTP-based solutions that follow the commonly accepted conventions for REST APIs. You can choose a Web API template or select the references when you create a new web project from within visual studio. Recently I led a course for Web API Design at Microsoft Virtual Academy and through a series of modules provided tips, tricks, and best practices and demonstrated how to leverage Web API to build REST-based services.

Web API design is an intentional approach to building your APIs. It is especially important when your APIs may be consumed by third-party resources. The practices that make APIs easily discoverable and consumable work equally well for resources that are intended for internal use. Proper Web API design means paying attention to details such as how well the API may be consumed (including things like how the signature is exposed and whether or not the API supports content negotiation), compliance with standards such as common status codes, security, versioning, and of course compliance with REST practices.

How To: ASP.NET Web API Design

To learn more about Web API Design, watch this module:

The first basic steps for design include defining the resources you will expose and building support for or responding correctly to requests that use the widely accepted HTTP verbs (GET, POST, PUT, DELETE, etc.) Your application should also support content negotiation and provide data in a format that is requested by the client. There are many tools you can use to test your APIs as you develop them. All of these steps and an example of how to consume a REST API from jQuery are included in this module:

ASP.NET Web API Benefits

A major benefit of ASP.NET Web API is the ability to configure just about any behavior. You can use media formatters to handle different request types and build your own to handle custom formats. Web API ships with default components to handle serialization for XML and JSON and you can change how things are serialized (such as whether the output is indented and what casing is used for properties). Routes are used to map URIs to controllers and their methods. The new routing attributes make it easier than ever to fine-grain the signature of your API. Learn more about these features by watching the configuration module:

Web APIs Handle Data Entry and Validation

Many web applications use APIs to handle data entry and validation. Therefore, it is important for your APIs to be able to validate data in a consistent fashion so the client can respond appropriately. When bad data or calls are made, you should be able to handle the resulting errors and provide an appropriate response to the consumer. APIs can be programmed to respond with standard status codes using built-in helpers. You can also take advantage of an existing feature called data annotations to perform automatic validation of your entities. Web API provides several options to handle errors, from filters to global handlers for logging and managing uncaught exceptions. Learn more by watching this module:

Security in ASP.NET Web API Design

Security is an important part of any enterprise line of business application. Web API supports a variety of methods for authentication (identification of the consumer) and authorization (permissions for a consumer to access resources). The security module covers host-based authentication using common mechanisms like active directory and Windows authentication. I then demonstrate how to build completely custom authentication schemes using message handlers. This is followed by a demonstration of token-based authentication, custom authorization filters, and role-based authorization. Finally, I wrap by showing how to use built-in services to prevent cross-site request forgery. Watch the security module here:

The final module covers advanced design. Control how your API parses entities through parameter binding, type converters, and model binding. Learn how to deal with versioned APIs and discover how Azure API Services can be used to secure, document, and even monetize your APIs. These advanced design concepts are all covered in the last module:

You can download the full source code and slides for the course from GitHub.

ASP. NET Web API is a powerful technology that can help you build enterprise class REST-based APIs for your line of business applications.

Want to learn more?


Written by:

Leave a comment