Understanding Request URLs and Methods

The core premise of REST—and the only aspect for which there is broad agreement—is that a web service defines an API through a combination of URLs and HTTP methods such as GET and POST, which are also known as the HTTP verbs. The method specifies the type of operation, while the URL specifies the data object or objects that the operation applies to.

Understanding JSON

Most RESTful web services format the response data using the JavaScript Object Notation (JSON) format. JSON has become popular because it is simple and easily consumed by JavaScript clients. JSON is described in detail at www.json.org, but you don’t need to understand every aspect of JSON to create web services because ASP.NET Core provides all the features required to create JSON responses.

Enabling the MVC Framework

The AddControllers method defines the services that are required by the MVC framework, and the MapControllers method defines routes that will allow controllers to handle requests. You will see other methods used to configure the MVC framework used in later chapters, which provide access to different features, but the methods used in Listing 19-6 are the ones that configure the MVC framework for web services.

Creating a Controller

Controllers are classes whose methods, known as actions, can process HTTP requests. Controllers are discovered automatically when the application is started. The basic discovery process is simple: any public class whose name ends with Controller is a controller, and any public method a controller defines is an action. To demonstrate how simple a controller can be, create the WebApp/Controllers folder and add to it a file named ProductsController.cs with the code shown in Listing 19-7.

The ProductsController class meets the criteria that the MVC framework looks for in a controller. It defines public methods named GetProducts and GetProduct, which will be treated as actions.

Understanding Action Method Results

One of the main benefits provided by controllers is that the MVC Framework takes care of setting the response headers and serializing the data objects that are sent to the client. You can see this in the results defined by the action methods, like this:

...

[HttpGet("{id}")]

public Product GetProduct() {

...

When I used an endpoint, I had to work directly with the JSON serializer to create a string that can be written to the response and set the Content-Type header to tell the client that the response contained JSON data. The action method returns a Product object, which is processed automatically.

To see how the results from the action methods are handled, restart ASP.NET Core and request http://localhost:5000/api/products, which will produce the response shown on the left of Figure 19-4, which is produced by the GetProducts action method. Next, request http://localhost:5000/api/products/1, which will be handled by the GetProduct method and produce the result shown on the right side of Figure 19-4.

Using Dependency Injection in Controllers

A new instance of the controller class is created each time one of its actions is used to handle a request. The application’s services are used to resolve any dependencies the controller declares through its constructor and any dependencies that the action method defines. This allows services that are required by all actions to be handled through the constructor while still allowing individual actions to declare their own dependencies, as shown in Listing 19-8.

using Microsoft.AspNetCore.Mvc;

using WebApp.Models;

using System.Collections.Generic;

using Microsoft.Extensions.Logging;

using System.Linq;

namespace WebApp.Controllers {

    [Route("api/[controller]")]

    public class ProductsController: ControllerBase {

        private DataContext context;

        public ProductsController(DataContext ctx) {

            context = ctx;

        }

        [HttpGet]

        public IEnumerable<Product> GetProducts() {

            return context.Products;

        }

        [HttpGet("{id}")]

        public Product GetProduct([FromServices]

                ILogger<ProductsController> logger) {

            logger.LogDebug("GetProduct Action Invoked");

            return context.Products.FirstOrDefault();

        }

    }

}

Listing 19-8.

Using Services in the ProductsController.cs File in the Controllers Folder

The constructor declares a dependency on the DataContext service, which provides access to the application’s data. The services are resolved using the request scope, which means that a controller can request all services, without needing to understand their lifecycle.

The Entity Framework Core Context Service Lifecycle

A new Entity Framework Core context object is created for each controller. Some developers will try to refuse context objects as a perceived performance improvement, but this causes problems because data from one query can affect subsequent queries, as described in Chapter 20. Behind the scenes, Entity Framework Core efficiently manages the connections to the database, and you should not try to store or reuse context objects outside of the controller for which they are created.

The GetProducts action method uses the DataContext to request all the Product objects in the database. The GetProduct method also uses the DataContext service, but it declares a dependency on ILogger<T>, which is the logging service described in Chapter 15. Dependencies that are declared by action methods must be decorated with the FromServices attribute, like this:

...

public Product GetProduct([FromServices] ILogger<ProductsController> logger) {

...

By default, the MVC Framework attempts to find values for action method parameters from the request URL, and the FromServices attribute overrides this behavior. To see the use of the services in the controller, restart ASP.NET Core and request http://localhost:5000/api/products/1, which will produce the response shown in Figure 19-5. You will also see the following logging message in the application’s output:

...

dbug: WebApp.Controllers.ProductsController[0]

      GetProduct Action Invoked

...

Caution

One consequence of the controller lifecycle is that you can’t rely on side effects caused by methods being called in a specific sequence. So, for example, I can’t assign the ILogger<T> object received by the GetProduct method in Listing 19-8 to a property that can be read by the GetProducts action in later requests. Each controller object is used to handle one request, and only one action method will be invoked by the MVC Framework for each object.

Using Model Binding to Access Route Data

In the previous section, I noted that the MVC Framework uses the request URL to find values for action method parameters, a process known as model binding. Model binding is described in detail in Chapter 28, but Listing 19-9 shows a simple example.

using Microsoft.AspNetCore.Mvc;

using WebApp.Models;

using System.Collections.Generic;

using Microsoft.Extensions.Logging;

using System.Linq;

namespace WebApp.Controllers {

    [Route("api/[controller]")]

    public class ProductsController: ControllerBase {

        private DataContext context;

        public ProductsController(DataContext ctx) {

            context = ctx;

        }

        [HttpGet]

        public IEnumerable<Product> GetProducts() {

            return context.Products;

        }

        [HttpGet("{id}")]

        public Product GetProduct(long id,

                [FromServices] ILogger<ProductsController> logger) {

            logger.LogDebug("GetProduct Action Invoked");

            return context.Products.Find(id);

        }

    }

}

Listing 19-9.

Using Model Binding in the ProductsController.cs File in the Controllers Folder

The listing adds a long parameter named id to the GetProduct method. When the action method is invoked, the MVC Framework injects the value with the same name from the routing data, automatically converting it to a long value, which is used by the action to query the database using the LINQ Find method. The result is that the action method responds to the URL, which you can see by restarting ASP.NET Core and requesting http://localhost:5000/api/products/5, which will produce the response shown in Figure 19-6.

Model Binding from the Request Body

The model binding feature can also be used on the data in the request body, which allows clients to send data that is easily received by an action method. Listing 19-10 adds a new action method that responds to POST requests and allows clients to provide a JSON representation of the Product object in the request body.

using Microsoft.AspNetCore.Mvc;

using WebApp.Models;

using System.Collections.Generic;

using Microsoft.Extensions.Logging;

using System.Linq;

namespace WebApp.Controllers {

    [Route("api/[controller]")]

    public class ProductsController: ControllerBase {

        private DataContext context;

        public ProductsController(DataContext ctx) {

            context = ctx;

        }

        [HttpGet]

        public IEnumerable<Product> GetProducts() {

            return context.Products;

        }

        [HttpGet("{id}")]

        public Product GetProduct(long id,

                [FromServices] ILogger<ProductsController> logger) {

            logger.LogDebug("GetProduct Action Invoked");

            return context.Products.Find(id);

        }

        [HttpPost]

        public void SaveProduct([FromBody]Product product) {

            context.Products.Add(product);

            context.SaveChanges();

        }

    }

}

Listing 19-10.

Adding an Action in the ProductsController.cs File in the Controllers Folder

The new action relies on two attributes. The HttpPost attribute is applied to the action method and tells the MVC Framework that the action can process POST requests. The FromBody attribute is applied to the action’s parameter, and it specifies that the value for this parameter should be obtained by parsing the request body. When the action method is invoked, the MVC Framework will create a new Product object and populate its properties with the values in the request body. The model binding process can be complex and is usually combined with data validation, as described in Chapter 29, but for a simple demonstration, restart ASP.NET Core, open a new PowerShell command prompt, and run the command shown in Listing 19-11.

Invoke-RestMethod http://localhost:5000/api/products -Method POST -Body  (@{ Name="Soccer Boots"; Price=89.99; CategoryId=2; SupplierId=2} | ConvertTo-Json) -ContentType "application/json"

Listing 19-11.

Sending a POST Request to the Example Application

Once the command has executed, use a web browser to request http://localhost:5000/api/products, and you will see the new object that has been stored in the database, as shown in Figure 19-7.

Adding Additional Actions

Now that the basic features are in place, I can add actions that allow clients to replace and delete Product objects using the HTTP PUT and DELETE methods, as shown in Listing 19-12.

using Microsoft.AspNetCore.Mvc;

using WebApp.Models;

using System.Collections.Generic;

using Microsoft.Extensions.Logging;

using System.Linq;

namespace WebApp.Controllers {

    [Route("api/[controller]")]

    public class ProductsController: ControllerBase {

        private DataContext context;

        public ProductsController(DataContext ctx) {

            context = ctx;

        }

        [HttpGet]

        public IEnumerable<Product> GetProducts() {

            return context.Products;

        }

        [HttpGet("{id}")]

        public Product GetProduct(long id,

                [FromServices] ILogger<ProductsController> logger) {

            logger.LogDebug("GetProduct Action Invoked");

            return context.Products.Find(id);

        }

        [HttpPost]

        public void SaveProduct([FromBody]Product product) {

            context.Products.Add(product);

            context.SaveChanges();

        }

        [HttpPut]

        public void UpdateProduct([FromBody]Product product) {

            context.Products.Update(product);

            context.SaveChanges();

        }

        [HttpDelete("{id}")]

        public void DeleteProduct(long id) {

            context.Products.Remove(new Product() { ProductId = id });

            context.SaveChanges();

        }

    }

}

Listing 19-12.

Adding Actions in the ProductsController.cs File in the Controllers Folder

The UpdateProduct action is similar to the SaveProduct action and uses model binding to receive a Product object from the request body. The DeleteProduct action receives a primary key value from the URL and uses it to create a Product that has a value only for the ProductId property, which is required because Entity Framework Core works only with objects, but web service clients typically expect to be able to delete objects using just a key value.

Restart ASP.NET Core and then use a different PowerShell command prompt to run the command shown in Listing 19-13, which tests the UpdateProduct action.

Invoke-RestMethod http://localhost:5000/api/products -Method PUT -Body  (@{ ProductId=1; Name="Green Kayak"; Price=275; CategoryId=1; SupplierId=1} | ConvertTo-Json) -ContentType "application/json"

Listing 19-13.

Updating an Object

The command sends an HTTP PUT request whose body contains a replacement object. The action method receives the object through the model binding feature and updates the database. Next, run the command shown in Listing 19-14 to test the DeleteProduct action.

Invoke-RestMethod http://localhost:5000/api/products/2 -Method DELETE

Listing 19-14.

Deleting an Object

This command sends an HTTP DELETE request, which will delete the object whose ProductId property is 2. To see the effect of the changes, use the browser to request http://localhost:5000/api/products, which will send a GET request that is handled by the GetProducts action and produce the response shown in Figure 19-8.

Using Asynchronous Actions

The ASP.NET Core platform processes each request by assigning a thread from a pool. The number of requests that can be processed concurrently is limited to the size of the pool, and a thread can’t be used to process any other request while it is waiting for an action to produce a result.

Actions that depend on external resources can cause a request thread to wait for an extended period. A database server, for example, may have its own concurrency limits and may queue up queries until they can be executed. The ASP.NET Core request thread is unavailable to process any other requests until the database produces a result for the action, which then produces a response that can be sent to the HTTP client.

This problem can be addressed by defining asynchronous actions, which allow ASP.NET Core threads to process other requests when they would otherwise be blocked, increasing the number of HTTP requests that the application can process simultaneously. Listing 19-15 revises the controller to use asynchronous actions.

Entity Framework Core provides asynchronous versions of some methods, such as FindAsync, AdddAsync, and SaveChangesAsync, and I have used these with the await keyword. Not all operations can be performed asynchronously, which is why the Update and Remove methods are unchanged.

For some operations—including LINQ queries to the database—the IAsyncEnumerable<T> interface can be used, which denotes a sequence of objects that should be enumerated asynchronously and prevents the ASP.NET Core request thread from waiting for each object to be produced by the database, as explained in Chapter 5.

There is no change to the responses produced by the controller, but the threads that ASP.NET Core assigns to process each request are not necessarily blocked by the action methods.

Preventing Over-Binding

By default, Entity Framework Core configures the database to assign primary key values when new objects are stored. This means the application doesn’t have to worry about keeping track of which key values have already been assigned and allows multiple applications to share the same database without the need to coordinate key allocation. The Product data model class needs a ProductId property, but the model binding process doesn’t understand the significance of the property and adds any values that the client provides to the objects it creates, which causes the exception in the SaveProduct action method.

This is known as over-binding, and it can cause serious problems when a client provides values that the developer wasn’t expecting. At best, the application will behave unexpectedly, but this technique has been used to subvert application security and grant users more access than they should have.

Restart ASP.NET Core and repeat the command from Listing 19-16, and you will see the response shown in Figure 19-9. The client has included the ProductId value, but it is ignored by the model binding process, which discards values for read-only properties. (You may see a different value for the ProductId property when you run this example depending on the changes you made to the database before running the command.)

Using Action Results

There is no matching object in the database, which means that the GetProduct action method returns null. When the MVC Framework receives null from an action method, it returns the 204 status code, which indicates a successful request that has produced no data. Not all web services behave this way, and a common alternative is to return a 404 response, indicating not found.

Similarly, the SaveProducts action will return a 200 response when it stores an object, but since the primary key isn’t generated until the data is stored, the client doesn’t know what key value was assigned.

Action methods can direct the MVC Framework to send a specific response by returning an object that implements the IActionResult interface, which is known as an action result. This allows the action method to specify the type of response that is required without having to produce it directly using the HttpResponse object.

Restart ASP.NET Core and repeat the command from Listing 19-19, and you will see an exception, which is how the Invoke-WebRequest command responds to error status codes, such as the 404 Not Found returned by the GetProduct action method.

Validating Data

The Required attribute denotes properties for which the client must provide a value and can be applied to properties that are assigned null when there is no value in the request. The Range attribute requires a value between upper and lower limits and is used for primitive types that will default to zero when there is no value in the request.

The ModelState property is inherited from the ControllerBase class, and the IsValid property returns true if the model binding process has produced data that meets the validation criteria. If the data received from the client is valid, then the action result from the Ok method is returned. If the data sent by the client fails the validation check, then the IsValid property will be false, and the action result from the BadRequest method is used instead. The BadRequest method accepts the object returned by the ModelState property, which is used to describe the validation errors to the client. (There is no standard way to describe validation errors, so the client may rely only on the 400 status code to determine that there is a problem.)

You can see examples of working with validation messages in Chapter 29 where the validation feature is described in detail.

Applying the API Controller Attribute

Using the ApiController attribute is optional, but it helps produce concise web service controllers.

Omitting Null Properties

The request was handled by the GetProduct action method, and the category and supplier values in the response will always be null because the action doesn’t ask Entity Framework Core to populate these properties.

Configuring the JSON Serializer

The JSON serializer can be configured to omit properties whose value is null when it serializes objects. The serializer is configured using the options pattern in the Startup class, as shown in Listing 19-31.

using System;

using System.Collections.Generic;

using System.Linq;

using System.Threading.Tasks;

using Microsoft.AspNetCore.Builder;

using Microsoft.AspNetCore.Hosting;

using Microsoft.AspNetCore.Http;

using Microsoft.Extensions.DependencyInjection;

using Microsoft.Extensions.Hosting;

using Microsoft.Extensions.Configuration;

using Microsoft.EntityFrameworkCore;

using WebApp.Models;

using Microsoft.AspNetCore.Mvc;

namespace WebApp {

    public class Startup {

        public Startup(IConfiguration config) {

            Configuration = config;

        }

        public IConfiguration Configuration { get; set; }

        public void ConfigureServices(IServiceCollection services) {

            services.AddDbContext<DataContext>(opts => {

                opts.UseSqlServer(Configuration[

                    "ConnectionStrings:ProductConnection"]);

                opts.EnableSensitiveDataLogging(true);

            });

            services.AddControllers();

            services.Configure<JsonOptions>(opts => {

                opts.JsonSerializerOptions.IgnoreNullValues = true;

            });

        }

        public void Configure(IApplicationBuilder app, DataContext context) {

            app.UseDeveloperExceptionPage();

            app.UseRouting();

            app.UseMiddleware<TestMiddleware>();

            app.UseEndpoints(endpoints => {

                endpoints.MapGet("/", async context => {

                    await context.Response.WriteAsync("Hello World!");

                });

                endpoints.MapControllers();

            });

            SeedData.SeedDatabase(context);

        }

    }

}

Listing 19-31.

Configuring the JSON Serializer in the Startup.cs File in the WebApp Folder

The JSON serializer is configured using the JsonSerializerOptions property of the JsonOptions class, and null values are discarded when the IgnoreNullValues property is true.

This configuration change affects all JSON responses and should be used with caution, especially if any of your data model classes use null values to impart information to the client. To see the effect of the change, restart ASP.NET Core and use a browser to request http://localhost:5000/api/products, which will produce the response shown in Figure 19-10.