Web API

In this section we will look at the Web API technology.

What is it?

Web API is a technology from Microsoft within the ASP.net stack which is intended to help developers build HTTP based services. Web API is intended to allow developers to build RESTful API’s which can be easily consumed by a wide range of client applications. A Web API component allows a service to be provided and also to be consumed via libraries within the .net stack.

The service communication will occur in a point to point style channel over HTTP. With Web API one of the key intentions is that your service is highly interoperable. The below picture shows a representation of this communication.

Features

The main features of Web API are:

• Support for JSON and XML – JSON and XML are the most common data formats for flowing
• CORS – Cross Origin Resource Sharing – CORS support allows a website to make an AJAX call to a different domain from the one which rendered the page.
• Attribute Routing – The ability to route HTTP Verbs to action attributes on your .net methods to simplify creating more powerful RESTful services
• OData Support
• Hosting in IIS or in custom application

Strengths

The key strength of Web API is that is simplifies HTTP services from the perspective of both developing a service and consuming a service. The simplicity is its strength.
Web API provides a solid foundation for building REST services on the Microsoft stack.

Weaknesses

The weaknesses of Web API are probably less around the technology and more around when you try to get it to do something for which it is not intended. An example of this could be when you want to do features in an HTTP communication which really require SOAP to be used on top of HTTP. As an example if you want to use something like the WS- protocols then you cant use them and that is by design. If you need something like the ability to implement a router such as with the WCF Routing service then you are using features which arent in the REST/WEB API stack and arent intended to be.

There are also some in thinks that Web API will inherit from the REST vs SOAP debate.

The key thing here is that if you understand some of the constraints around REST and Web API and use them for what they are intended to be used for then you should find it relatively easy to develop successful things with Web API. If you try to get it to do things for which it wasnt really intended then you will probably have some problems.

Dependencies

Web API doesnt really depend on that many things. You will need to host your Web API service inside an IIS application or an Azure Web App. This is really just the hosting and execution environment for your API. You also have some dependencies on NuGet packages within the Visual Studio project you will create for your Web API project. There are quite a lot of them but in most cases they will just exist in the background and you will not really touch them.

Costs

There is no cost for web API itself. Its free as part of the .net framework.

Related Technologies

The following technologies are similar or have a relationship with Web API:

WCF

Web API and WCF are competing technologies in that they both give you a way to implement HTTP based communication. Normally it depends if you need SOAP based communications you will use WCF and if you want REST based services you would use Web API.

WCF does have some features which support REST based services but this has probably been superseded by Web API even though they are still supported in WCF.

Open API, Swagger/Swashbuckle

Open API is the name for what was formerly Swagger specification and is a specification which is intended to allow you to provide a descriptive representation of your API. Think of it being similar to WSDL for Web Services.
Open API provides a bunch of features which make your API much easier to manage and for consumers to use it. Swagger and Swashbuckle are a set of tools which will help you to build API's on .net with Web API which adhere to these specifications. Swagger is a .net addon available via NuGet to implement Swagger support in your Web API. Anyone implementing a web API component should be looking to add Swagger support to it as it provides so many useful things for minimal setup.

Recommended Positioning

Web API is a green light technology and one you can safely and reliably bet on when building API components on the Microsoft technology stack.

You will have a couple of decisions to make such as where to host your component, there are a number of cloud and on premise choices for this.
You will also need to consider if you want to use the .net core or .net framework versions of Web API. One option could be to use Azure Functions which will abstract you from some of the scafolding of a service and let you focus on functionality.