Understanding web service acronyms

Understanding Windows Communication Foundation (WCF)

.NET Framework 3.0 and later includes a remote procedure call (RPC) technology named Windows Communication Foundation (WCF). RPC technologies enable code on one system to execute code on another over a network.

Understanding HTTP requests and responses for Web APIs

GET /path/to/resource
Accept: application/json

Common responses include success and multiple types of failure, as shown in the following table:

Other common types of HTTP requests include POST, PUT, PATCH, or DELETE that create, modify, or delete resources.

POST /path/to/resource
Content-Length: 123
Content-Type: application/json

PUT /path/to/resource
Content-Length: 123
Content-Type: application/json

To update an existing resource more efficiently, you might make a PATCH request with a body that contains an object with only the properties that need changing, as shown in the following code:

PATCH /path/to/resource
Content-Length: 123
Content-Type: application/json

To delete an existing resource, you might make a DELETE request, as shown in the following code:

DELETE /path/to/resource

As well as the responses shown in the table above for a GET request, all the types of requests that create, modify, or delete a resource have additional possible common responses, as shown in the following table:

Creating an ASP.NET Core Web API project

Your methods should be as shown highlighted in the following code:

// GET /weatherforecast
[HttpGet]
public IEnumerable<WeatherForecast> Get() // original method
{
  return Get(5); // five day forecast
}
// GET /weatherforecast/7
[HttpGet("{days:int}")]
public IEnumerable<WeatherForecast> Get(int days) // new method
{
  return Enumerable.Range(1, days).Select(index =>
    new WeatherForecast
    {
      Date = DateTime.Now.AddDays(index),
      TemperatureC = Random.Shared.Next(-20, 55),
      Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .ToArray();
}

In the [HttpGet] attribute, note the route format pattern {days:int} that constrains the days parameter to int values.

Reviewing the web service's functionality

Now, we will test the web service's functionality:

Creating a web service for the Northwind database

We will reference the Entity Framework Core entity data model for the Northwind database that you created in Chapter 13, Introducing Practical Applications of C# and .NET:

Creating data repositories for entities

• C for Create
• R for Retrieve (or Read)
• U for Update
• D for Delete

We will follow modern good practice and make the repository API asynchronous. It will be instantiated by a Controller class using constructor parameter injection, so a new instance is created to handle every HTTP request:

1. In the Northwind.WebApi project, create a folder named Repositories.
2. Add two class files to the Repositories folder named ICustomerRepository.cs and CustomerRepository.cs.
3. The ICustomerRepository interface will define five methods, as shown in the following code:

   using Packt.Shared; // Customer
   namespace Northwind.WebApi.Repositories;
   public interface ICustomerRepository
   {
     Task<Customer?> CreateAsync(Customer c);
     Task<IEnumerable<Customer>> RetrieveAllAsync();
     Task<Customer?> RetrieveAsync(string id);
     Task<Customer?> UpdateAsync(string id, Customer c);
     Task<bool?> DeleteAsync(string id);
   }
   

4. The CustomerRepository class will implement the five methods, remembering that methods that use await inside them must be marked as async, as shown in the following code:

   using Microsoft.EntityFrameworkCore.ChangeTracking; // EntityEntry<T>
   using Packt.Shared; // Customer
   using System.Collections.Concurrent; // ConcurrentDictionary
   namespace Northwind.WebApi.Repositories;
   public class CustomerRepository : ICustomerRepository
   {
     // use a static thread-safe dictionary field to cache the customers
     private static ConcurrentDictionary
       <string, Customer>? customersCache;
     // use an instance data context field because it should not be
     // cached due to their internal caching
     private NorthwindContext db;
     public CustomerRepository(NorthwindContext injectedContext)
     {
       db = injectedContext;
       // pre-load customers from database as a normal
       // Dictionary with CustomerId as the key,
       // then convert to a thread-safe ConcurrentDictionary
       if (customersCache is null)
       {
         customersCache = new ConcurrentDictionary<string, Customer>(
           db.Customers.ToDictionary(c => c.CustomerId));
       }
     }
     public async Task<Customer?> CreateAsync(Customer c)
     {
       // normalize CustomerId into uppercase
       c.CustomerId = c.CustomerId.ToUpper();
       // add to database using EF Core
       EntityEntry<Customer> added = await db.Customers.AddAsync(c);
       int affected = await db.SaveChangesAsync();
       if (affected == 1)
       {
         if (customersCache is null) return c;
         // if the customer is new, add it to cache, else
         // call UpdateCache method
         return customersCache.AddOrUpdate(c.CustomerId, c, UpdateCache);
       }
       else
       {
         return null;
       }
     }
     public Task<IEnumerable<Customer>> RetrieveAllAsync()
     {
       // for performance, get from cache
       return Task.FromResult(customersCache is null 
           ? Enumerable.Empty<Customer>() : customersCache.Values);
     }
     public Task<Customer?> RetrieveAsync(string id)
     {
       // for performance, get from cache
       id = id.ToUpper();
       if (customersCache is null) return null!;
       customersCache.TryGetValue(id, out Customer? c);
       return Task.FromResult(c);
     }
     private Customer UpdateCache(string id, Customer c)
     {
       Customer? old;
       if (customersCache is not null)
       {
         if (customersCache.TryGetValue(id, out old))
         {
           if (customersCache.TryUpdate(id, c, old))
           {
             return c;
           }
         }
       }
       return null!;
     }
     public async Task<Customer?> UpdateAsync(string id, Customer c)
     {
       // normalize customer Id
       id = id.ToUpper();
       c.CustomerId = c.CustomerId.ToUpper();
       // update in database
       db.Customers.Update(c);
       int affected = await db.SaveChangesAsync();
       if (affected == 1)
       {
         // update in cache
         return UpdateCache(id, c);
       }
       return null;
     }
     public async Task<bool?> DeleteAsync(string id)
     {
       id = id.ToUpper();
       // remove from database
       Customer? c = db.Customers.Find(id);
       if (c is null) return null;
       db.Customers.Remove(c);
       int affected = await db.SaveChangesAsync();
       if (affected == 1)
       {
         if (customersCache is null) return null;
         // remove from cache
         return customersCache.TryRemove(id, out c);
       }
       else
       {
         return null;
       }
     }
   }
   

Implementing a Web API controller

With MVC controllers, a route like /home/index tells us the controller class name and the action method name, for example, the HomeController class and the Index action method.

With Web API controllers, a route like /weatherforecast only tells us the controller class name, for example, WeatherForecastController. To determine the action method name to execute, we must map HTTP methods like GET and POST to methods in the controller class.

You should decorate controller methods with the following attributes to indicate the HTTP method that they will respond to:

Understanding action method return types

For more control over the response, there are helper methods that return an ActionResult wrapper around the .NET type.

Declare the action method's return type to be IActionResult if it could return different return types based on inputs or other variables. Declare the action method's return type to be ActionResult<T> if it will only return a single type but with different status codes.

For example, an action method that gets a product based on an id parameter would be decorated with three attributes – one to indicate that it responds to GET requests and has an id parameter, and two to indicate what happens when it succeeds and when the client has supplied an invalid product ID, as shown in the following code:

[HttpGet("{id}")]
[ProducesResponseType(200, Type = typeof(Product))] 
[ProducesResponseType(404)]
public IActionResult Get(string id)

The ControllerBase class has methods to make it easy to return different responses, as shown in the following table:

Configuring the customer repository and Web API controller

Now you will configure the repository so that it can be called from within a Web API controller.

To show an example of differentiating between MVC and Web API controllers using routes, we will use the common /api URL prefix convention for the customers controller:

When an HTTP request is received by the service, then it will create an instance of the Controller class, call the appropriate action method, return the response in the format preferred by the client, and release the resources used by the controller, including the repository and its data context.

Specifying problem details

A feature added in ASP.NET Core 2.1 and later is an implementation of a web standard for specifying problem details.

If you want to take control, then you can create a ProblemDetails instance yourself and include additional information.

Let's simulate a bad request that needs custom data returned to the client:

Controlling XML serialization

However, the XmlSerializer cannot serialize interfaces, and our entity classes use ICollection<T> to define related child entities. This causes a warning at runtime, for example, for the Customer class and its Orders property, as shown in the following output:

warn: Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerOutputFormatter[1]
An error occurred while trying to create an XmlSerializer for the type 'Packt.Shared.Customer'.
System.InvalidOperationException: There was an error reflecting type 'Packt.Shared.Customer'.
---> System.InvalidOperationException: Cannot serialize member 'Packt.
Shared.Customer.Orders' of type 'System.Collections.Generic.ICollection`1[[Packt. Shared.Order, Northwind.Common.EntityModels, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null]]', see inner exception for more details.

We can prevent this warning by excluding the Orders property when serializing a Customer to XML:

Documenting and testing web services

Testing GET requests using a browser

Unlike with country names, we do not need to worry about casing for the customer id value because inside the controller class, we normalized the string value to uppercase in code.

But how can we test the other HTTP methods, such as POST, PUT, and DELETE? And how can we document our web service so it's easy for anyone to understand how to interact with it?

Making GET requests using REST Client

We will start by creating a file for testing GET requests:

Figure 16.7: Sending a request for XML and getting a response using REST Client

Making other requests using REST Client

Next, we will create a file for testing other requests like POST:

Figure 16.9: Adding a new customer

Now that we've seen a quick and easy way to test our service, which also happens to be a great way to learn HTTP, what about external developers? We want it to be as easy as possible for them to learn and then call our service. For that purpose, we will use Swagger.

Understanding Swagger

Developers can use the OpenAPI Specification for a Web API to automatically generate strongly-typed client-side code in their preferred language or library.

Let's review how Swagger is enabled for our web service using the Swashbuckle package:

Testing requests with Swagger UI

You are now ready to test an HTTP request using Swagger:

Enabling HTTP logging

• Information about the HTTP request
• Headers
• Body
• Information about the HTTP response

Let's see HTTP logging in action:

You are now ready to build applications that consume your web service.

Consuming web services using HTTP clients

Understanding HttpClient

Usually, when a type implements IDisposable, you should create it inside a using statement to ensure that it is disposed of as soon as possible. HttpClient is different because it is shared, reentrant, and partially thread-safe.

The problem has to do with how the underlying network sockets have to be managed. The bottom line is that you should use a single instance of it for each HTTP endpoint that you consume during the life of your application. This will allow each HttpClient instance to have defaults set that are appropriate for the endpoint it works with, while managing the underlying network sockets efficiently.

Configuring HTTP clients using HttpClientFactory

In the following example, we will use the Northwind MVC website as a client to the Northwind Web API service. Since both need to be hosted on a web server simultaneously, we first need to configure them to use different port numbers, as shown in the following list:

• The Northwind Web API service will listen on port 5002 using HTTPS.
• The Northwind MVC website will continue to listen on port 5000 using HTTP and port 5001 using HTTPS.

Let's configure those ports:

1. In the Northwind.WebApi project, in Program.cs, add an extension method call to UseUrls to specify port 5002 for HTTPS, as shown highlighted in the following code:

   var builder = WebApplication.CreateBuilder(args);
   builder.WebHost.UseUrls("https://localhost:5002/");
   

2. In the Northwind.Mvc project, open Program.cs and import the namespace for working with HTTP client factory, as shown in the following code:

   using System.Net.Http.Headers; // MediaTypeWithQualityHeaderValue
   

3. Add a statement to enable HttpClientFactory with a named client to make calls to the Northwind Web API service using HTTPS on port 5002 and request JSON as the default response format, as shown in the following code:

   builder.Services.AddHttpClient(name: "Northwind.WebApi",
     configureClient: options =>
     {
       options.BaseAddress = new Uri("https://localhost:5002/");
       options.DefaultRequestHeaders.Accept.Add(
         new MediaTypeWithQualityHeaderValue(
         "application/json", 1.0));
     });
   

Getting customers as JSON in the controller

Enabling Cross-Origin Resource Sharing

Since our web service is hosted on port 5002 and our MVC website is hosted on ports 5000 and 5001, they are considered different origins and so resources cannot be shared.

It would be useful to enable CORS on the server and configure our web service to only allow requests that originate from the MVC website:

You have successfully built a web service and called it from an MVC website.

Implementing advanced features for web services

Implementing a Health Check API

ASP.NET Core 2.2 and later makes it easy to implement more detailed website health checks. For example, your website might be live, but is it ready? Can it retrieve data from its database?

Let's add basic health check capabilities to our web service:

Implementing Open API analyzers and conventions

In ASP.NET Core 2.2 or later, there are API analyzers that reflect over controller classes that have been annotated with the [ApiController] attribute to document it automatically. The analyzer assumes some API conventions.

To use it, your project must enable the OpenAPI Analyzers, as shown highlighted in the following markup:

<PropertyGroup>
  <TargetFramework>net6.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

After installing, controllers that have not been properly decorated should have warnings (green squiggles) and warnings when you compile the source code. For example, the WeatherForecastController class.

Automatic code fixes can then add the appropriate [Produces] and [ProducesResponseType] attributes, although this only currently works in Visual Studio. In Visual Studio Code, you will see warnings about where the analyzer thinks you should add attributes, but you must add them yourself.

Implementing transient fault handling

To handle these transient faults, Microsoft recommends that you use the third-party library Polly to implement automatic retries with exponential backoff. You define a policy, and the library handles everything else.

The easiest way to add these headers is using a middleware class:

Building web services using minimal APIs

You might remember the weather forecast service that is provided in the Web API project template. It shows the use of a controller class to return a five-day weather forecast using faked data. We will now recreate that weather service using minimal APIs.

First, the weather service has a class to represent a single weather forecast. We will need to use this class in multiple projects, so let's create a class library for that:

1. Use your preferred code editor to add a new project, as defined in the following list:
   1. Project template: Class Library / classlib
   2. Workspace/solution file and folder: PracticalApps
   3. Project file and folder: Northwind.Common
2. Rename Class1.cs to WeatherForecast.cs.
3. Modify WeatherForecast.cs, as shown in the following code:

   namespace Northwind.Common
   {
     public class WeatherForecast
     {
       public static readonly string[] Summaries = new[]
       {
         "Freezing", "Bracing", "Chilly", "Cool", "Mild",
         "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
       };
       public DateTime Date { get; set; }
       public int TemperatureC { get; set; }
       public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
       public string? Summary { get; set; }
     }
   }
   

Building a weather service using minimal APIs

Testing the minimal weather service

1. Start the web service project.
2. If you are not using Visual Studio 2022, start Chrome and navigate to https://localhost:5003/api/weather.
3. Note the Web API service should return a JSON document with five random weather forecast objects in an array.
4. Close Chrome and shut down the web server.

Adding weather forecasts to the Northwind website home page

Practicing and exploring

Test your knowledge and understanding by answering some questions, get some hands-on practice, and explore this chapter's topics with deeper research.

Exercise 16.1 – Test your knowledge

Answer the following questions:

1. Which class should you inherit from to create a controller class for an ASP.NET Core Web API service?
2. If you decorate your controller class with the [ApiController] attribute to get default behavior like automatic 400 responses for invalid models, what else must you do?
3. What must you do to specify which controller action method will be executed in response to an HTTP request?
4. What must you do to specify what responses should be expected when calling an action method?
5. List three methods that can be called to return responses with different status codes.
6. List four ways that you can test a web service.
7. Why should you not wrap your use of HttpClient in a using statement to dispose of it when you are finished even though it implements the IDisposable interface, and what should you use instead?
8. What does the acronym CORS stand for and why is it important to enable it in a web service?
9. How can you enable clients to detect if your web service is healthy with ASP.NET Core 2.2 and later?
10. What benefits does endpoint routing provide?

Exercise 16.2 – Practice creating and deleting customers with HttpClient

Extend the Northwind.Mvc website project to have pages where a visitor can fill in a form to create a new customer, or search for a customer and then delete them. The MVC controller should make calls to the Northwind web service to create and delete customers.

Exercise 16.3 – Explore topics

Use the links on the following page to learn more detail about the topics covered in this chapter: