Get to know ASP.NET Core Web API [Tutorial]

ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework. In today’s post we shall be looking at the following topics:

Quick recap of MVC framework

Why Web APIs were incepted and it's evolution?

Introduction to .NET Core?

Overview of ASP.NET Core architecture

This article is an extract from the book Mastering ASP.NET Web API written by Mithun Pattankar and Malendra Hurbuns.

Quick recap of MVC framework

Model-View-Controller (MVC) is a powerful and elegant way of separating concerns within an application and applies itself extremely well to web applications.

With ASP.NETMVC, it's translated roughly as follows:

Models (M): These are the classes that represent the domain you are interested in. These domain objects often encapsulate data stored in a database as well as code that manipulates the data and enforces domain-specific business logic. With ASP.NETMVC, this is most likely a Data Access Layer of some kind, using a tool like Entity Framework or NHibernate or classic ADO.NET.

View (V): This is a template to dynamically generate HTML.

Controller(C): This is a special class that manages the relationship between the View and the Model. It responds to user input, talks to the Model, and decides which view to render (if any). In ASP.NETMVC, this class is conventionally denoted by the suffix Controller.

Why Web APIs were incepted and it's evolution?

Looking back to days when ASP.NETASMX-based XML web service was widely used for building service-oriented applications, it was easiest way to create SOAP-based service which can be used by both .NET applications and non .NET applications. It was available only over HTTP.

Around 2006, Microsoft released Windows Communication Foundation (WCF).WCF was and even now a powerful technology for building SOA-based applications. It was giant leap in the world of Microsoft .NET world.

WCF was flexible enough to be configured as HTTP service, Remoting service, TCP service, and so on. Using Contracts of WCF, we would keep entire business logic code base same and expose the service as HTTP based or non HTTP based via SOAP/ non SOAP.

Until 2010 the ASMX based XML web service or WCF service were widely used in client server based applications, in-fact everything was running smoothly.

But the developers of .NET or non .NET community started to feel need for completely new SOA technology for client server applications. Some of reasons behind them were as follows:

With applications in production, the amount of data while communicating started to explode and transferring them over the network was bandwidth consuming.

SOAP being light weight to some extent started to show signs of payload increase. A few KB SOAP packets were becoming few MBs of data transfer.

Consuming the SOAP service in applications lead to huge applications size because of WSDL and proxy generation. This was even worse when it was used in web applications.

Any changes to SOAP services lead to repeat of consuming them by proxy generation. This wasn't easy task for any developers.

JavaScript-based web frameworks were getting released and gaining ground for much simpler way of web development. Consuming SOAP-based services were not that optimal way.

Hand-held devices were becoming popular like tablets, smartphones. They had more focused applications and needed very lightweight service oriented approach.

Browser based Single Page Applications (SPA) was gaining ground very rapidly. Using SOAP based services for quite heavy for these SPA.

Microsoft released REST based WCF components which can be configured to respond in JSON or XML, but even then it was WCF which was heavy technology to be used.

Applications where no longer just large enterprise services, but there was need was more focused light weight service to be up & running in few days and much easier to use.

Any developer who has seen evolving nature of SOA based technologies like ASMX, WCF or any SOAP based felt the need to have much lighter, HTTP based services.

HTTP only, JSON compatible POCO based lightweight services was need of the hour and concept of Web API started gaining momentum.

What is Web API?

A Web API is a programmatic interface to a system that is accessed via standard HTTP methods and headers. A Web API can be accessed by a variety of HTTP clients, including browsers and mobile devices.

For Web API to be successful HTTP based service, it needed strong web infrastructure like hosting, caching, concurrency, logging, security etc. One of the best web infrastructure was none other than ASP.NET.

ASP.NET either in form Web Form or MVC was widely adopted, so the solid base for web infrastructure was mature enough to be extended as Web API.

Microsoft responded to community needs by creating ASP.NET Web API- a super-simple yet very powerful framework for building HTTP-only, JSON-by-default web services without all the fuss of WCF.

ASP.NET Web API can be used to build REST based services in matter of minutes and can easily consumed with any front end technologies. It used IIS (mostly) for hosting, caching, concurrency etc. features, it became quite popular.

It was launched in 2012 with most basics needs for HTTP based services like convention-based Routing, HTTP Request and Response messages.

Later Microsoft released much bigger and better ASP.NET Web API 2 along with ASP.NETMVC 5 in Visual Studio 2013.

ASP.NET Web API 2 evolved at much faster pace with these features.

Installed via NuGet

Installing of Web API 2 was made simpler by using NuGet, either create empty ASP.NET or MVC project and then run command in NuGet Package Manager Console:

Install-Package Microsoft.AspNet.WebApi

Attribute Routing

Initial release of Web API was based on convention-based routing meaning we define one or more route templates and work around it. It's simple without much fuss as routing logic in a single place & it's applied across all controllers.

The real world applications are more complicated with resources (controllers/ actions) have child resources like customers having orders, books having authors etc. In such cases convention-based routing is not scalable.

Web API 2 introduced a new concept of Attribute Routing which uses attributes in programming languages to define routes. One straight forward advantage is developer has full controls how URIs for Web API are formed.

Here is quick snippet of Attribute Routing:

[Route("customers/{customerId}/orders")]
public IEnumerable<Order>GetOrdersByCustomer(intcustomerId) { ... }

For more understanding on this, read Attribute Routing in ASP.NET Web API 2 (https://www.asp.net/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2)

OWIN self-host

ASP.NET Web API lives on ASP.NET framework, leading to think that it can be hosted on IIS only. The Web API 2 came new hosting package.

Microsoft.AspNet.WebApi.OwinSelfHost

With this package it can self-hosted outside IIS using OWIN/Katana.

CORS (Cross Origin Resource Sharing)

Any Web API developed either using .NET or non .NET technologies and meant to be used across different web frameworks, then enabling CORS is must.

A must read on CORS&ASP.NET Web API 2 (https://www.asp.net/web-api/overview/security/enabling-cross-origin-requests-in-web-api).

IHTTPActionResult and Web API OData improvements are other few notable features which helped evolve Web API 2 as strong technology for developing HTTP based services.

ASP.NET Web API 2 has becoming more powerful over the years with C# language improvements like Asynchronous programming using Async/ Await, LINQ, Entity Framework Integration, Dependency Injection with DI frameworks, and so on.

ASP.NET into Open Source world

Every technology has to evolve with growing needs and advancements in hardware, network and software industry, ASP.NET Web API is no exception to that.

Some of the evolution that ASP.NET Web API should undergo from perspectives of developer community, enterprises and end users are:

NETMVC and Web API even though part of ASP.NET stack but their implementation and code base is different. A unified code base reduces burden of maintaining them.

It's known that Web API's are consumed by various clients like web applications, Native apps, and Hybrid apps, desktop applications using different technologies (.NET or non .NET). But how about developing Web API in cross platform way, need not rely always on Windows OS/ Visual Studio IDE.

Open sourcing the ASP.NET stack so that it's adopted on much bigger scale.

End users are benefitted with open source innovations.

We saw that why Web APIs were incepted, how they evolved into powerful HTTP based service and some evolutions required. With these thoughts Microsoft made an entry into world of Open Source by launching .NET Core and ASP.NET Core 1.0.

What is .NET Core?

.NET Core is a cross-platform free and open-source managed software framework similar to .NET Framework. It consists of CoreCLR, a complete cross-platform runtime implementation of CLR.

.NET Core 1.0 was released on 27 June 2016 along with Visual Studio 2015 Update 3, which enables .NET Core development.

In much simpler terms .NET Core applications can be developed, tested, deployed on cross platforms such as Windows, Linux flavours, macOS systems.

With help of .NET Core, we don't really need Windows OS and in particular Visual Studio IDE to develop ASP.NET web applications, command-line apps, libraries, and UWP apps.

In short, let's understand .NET Core components:

CoreCLR:It is a virtual machine that manages the execution of .NET programs. CoreCLRmeans Core Common Language Runtime, it includes the garbage collector, JIT compiler, base .NET data types and many low-level classes.

CoreFX: .NET Core foundational libraries likes class for collections, file systems, console, XML, Async and many others.

CoreRT: .NET Core runtime optimized for AOT (ahead of time compilation) scenarios, with the accompanying .NET Native compiler toolchain. Its main responsibility is to do native compilation of code written in any of our favorite .NET programming language.

.NET Core shares subset of original .NET framework, plus it comes with its own set of APIs that is not part of .NET framework. This results in some shared APIs that can be used by both .NET core and .NET framework.

A .Net Core application can easily work on existing .NET Framework but not vice versa.

.NET Core provides a CLI (Command Line Interface) for an execution entry point for operating systems and provides developer services like compilation and package management.

The following are the .NET Core interesting points to know:

.NET Core can be installed on cross platforms like Windows, Linux, andmacOS. It can be used in device, cloud, and embedded/IoT scenarios.

Visual Studio IDE is not mandatory to work with .NET Core, but when working on Windows OS we can leverage existing IDE knowledge to work.

.NET Core is modular, meaning that instead of assemblies, developers deal with NuGet packages.

.NET Core relies on its package manager to receive updates because cross platform technology can't rely on Windows Updates.

To learn .NET Core, we just need a shell, text editor and its runtime installed.

.NET Core comes with flexible deployment. It can be included in your app or installed side-by-side user- or machine-wide.

.NET Core apps can also be self-hosted/run as standalone apps.

.NET Core supports four cross-platform scenarios--ASP.NET Core web apps, command-line apps, libraries, and Universal Windows Platform apps.

It does not implement Windows Forms or WPF which render the standard GUI for desktop software on Windows.

At present only C# programming language can be used to write .NET Core apps. F# and VB support are on the way.

We will primarily focus on ASP.NET Core web apps which includes MVC and Web API. CLI apps, libraries will be covered briefly.

What is ASP.NET Core?

A new open-source and cross-platform framework for building modern cloud-based web applications using .NET.

ASP.NET Core is completely open-source, you can download it from GitHub. It's cross platform meaning you can develop ASP.NET Core apps on Linux/macOS and of course on Windows OS.

ASP.NET was first released almost 15 years back with .NET framework. Since then it's adopted by millions of developers for large, small applications. ASP.NET has evolved with many capabilities.

With .NET Core as cross platform, ASP.NET took a huge leap beyond boundaries of Windows OS environment for development and deployment of web applications.

ASP.NET Core overview

get-to-know-asp-net-core-web-api-tutorial-img-0

ASP.NET Core high level overview provides following insights:

NET Core runs both on Full .NET framework and .NET Core.

NET Core applications with full .NET framework can only be developed and deployed only Windows OS/Server.

When using .NET core, it can be developed and deployed on platform of choice. The logos of Windows, Linux, macOSindicates that you can work with ASP.NET Core.

NET Core when on non-Windows machine, use the .NET Core libraries to run the applications. It's obvious you won't have all full .NET libraries but most of them are available.

Developers working on ASP.NET Core can easily switch working on any machine not confined to Visual Studio 2015 IDE.

NET Core can run with different version of .NET Core.

ASP.NET Core has much more foundational improvements apart from being cross-platform, we gain following advantages of using ASP.NET Core:

Totally Modular: ASP.NET Core takes totally modular approach for application development, every component needed to build application are well factored into NuGet packages. Only add required packages through NuGet to keep overall application lightweight.

NET Core is no longer based on System.Web.dll.

Choose your editors and tools: Visual Studio IDE was used to develop ASP.NET applications on Windows OS box, now since we have moved beyond the Windows world. Then we will require IDE/editors/ Tools required for developingASP.NET applications on Linux/macOS. Microsoft developed powerful lightweight code editors for almost any type of web applications called as Visual Studio Code.

NET Core is such a framework that we don't need Visual Studio IDE/ code to develop applications. We can use code editors like Sublime, Vim also. To work with C# code in editors, installed and use OmniSharp plugin.

OmniSharp is a set of tooling, editor integrations and libraries that together create an ecosystem that allows you to have a great programming experience no matter what your editor and operating system of choice may be.

Integration with modern web frameworks: ASP.NET Core has powerful, seamless integration with modern web frameworks like Angular, Ember, NodeJS, and Bootstrap.

Using bower andNPM, we can work with modern web frameworks.

Cloud ready: ASP.NET Core apps are cloud ready with configuration system, it just seamlessly gets transitioned from on-premises to cloud.

Built in Dependency Injection.

Can be hosted on IIS or self-host in your own process or on nginx.

New light-weight and modular HTTP request pipeline.

Unified code base for Web UI and Web APIs. We will see more on this when we explore anatomy of ASP.NET Core application.

To summarize, we covered MVC framework and introduced .NET Core and its architecture.

You can leverage ASP.Net Web API to build professional web services and create powerful applications check out this book, Mastering ASP.NET Web API written by Mithun Pattankar and Malendra Hurbuns.

What is ASP.NET Core?

Why ASP.NET makes building apps for mobile and web easy – Interview with Jason de Oliveira

How to call an Azure function from an ASP.NET Core MVC application