BeautifulRestApi

Beautiful REST API design with ASP.NET Core and Ion

Hello! :wave: This repository contains an example API written in C# and ASP.NET Core 1.1. It uses the [Ion hypermedia specification][ion] as a starting point to model a consistent, clean REST API that embraces HATEOAS.

I use this example in my talk Building beautiful RESTful APIs with ASP.NET Core (follow the link to download the slides).

Deep dive video course

If you want a four-hour deep dive on REST, HATEOAS, Ion, API security, ASP.NET Core, and much more, check out my course [Building and Securing RESTful APIs in ASP.NET Core][lil-course] on LinkedIn Learning.

It covers everything in this example repository and a lot more. (If you don't have a LinkedIn Learning or Lynda subscription, send me an e-mail and I'll give you a coupon!)

Testing it out

1. Clone this repository
2. Build the solution using Visual Studio, or on the command line with dotnet build.
3. Run the project. The API will start up on http://localhost:50647, or http://localhost:5000 with dotnet run.
4. Use an HTTP client like Postman or Fiddler to GET http://localhost:50647.
5. HATEOAS
6. Profit! :moneybag:

Techniques for building RESTful APIs in ASP.NET Core

This example contains a number of tricks and techniques I've learned while building APIs in ASP.NET Core. If you have any suggestions to make it even better, let me know!

• Beautiful REST API design with ASP.NET Core and Ion
  • Deep dive video course
  • Testing it out
  • Techniques for building RESTful APIs in ASP.NET Core
    • Entity Framework Core in-memory for rapid prototyping
    • Model Ion links, resources, and collections
    • Basic API controllers and routing
    • Named routes pattern
    • Async/await best practices
    • Keep controllers lean
    • Validate model binding with an ActionFilter
    • Provide a root route
    • Serialize errors as JSON
    • Generate absolute URLs automatically with a filter
    • Map resources using AutoMapper
    • Use strongly-typed route parameter classes
    • Consume application configuration in services
    • Add paging to collections
    • More to come...

Entity Framework Core in-memory for rapid prototyping

The in-memory provider in Entity Framework Core makes it easy to rapidly prototype without having to worry about setting up a database. You can build and test against a fast in-memory store, and then swap it out for a real database when you're ready.

With the Microsoft.EntityFrameworkCore.InMemory package installed, create a DbContext:

public class ApiDbContext : DbContext
{
    public ApiDbContext(DbContextOptions options)
        : base(options)
    {
    }

    // DbSets...
}

The only difference between this and a "normal" DbContext is the addition of a constructor that takes a DbContextOptions<> parameter. This is required by the in-memory provider.

Then, wire up the in-memory provider in Startup.ConfigureServices:

services.AddDbContext(options =>
{
    // Use an in-memory database with a randomized database name (for testing)
    options.UseInMemoryDatabase(Guid.NewGuid().ToString());
});

The database will be empty when the application starts. To make prototyping and testing easy, you can add test data in Startup.cs:

// In Configure()
var dbContext = app.ApplicationServices.GetRequiredService();
AddTestData(dbContext);

private static void AddTestData(ApiDbContext context)
{
    context.Conversations.Add(new Models.ConversationEntity
    {
        Id = Guid.Parse("6f1e369b-29ce-4d43-b027-3756f03899a1"),
        CreatedAt = DateTimeOffset.UtcNow,
        Title = "Who is the coolest Avenger?"
    });

    // Make sure you save changes!
    context.SaveChanges();
}

Model Ion links, resources, and collections

[Ion][ion] provides a simple framework for describing REST objects in JSON. These Ion objects can be modeled as POCOs in C#. Here's a Link object:

public class Link
{
    public string Href { get; set; }

    // Since ASP.NET Core uses JSON.NET by default, serialization can be
    // fine-tuned with JSON.NET attributes
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore, DefaultValueHandling = DefaultValueHandling.Ignore)]
    [DefaultValue(GetMethod)]
    public string Method { get; set; }

    [JsonProperty(PropertyName = "rel", NullValueHandling = NullValueHandling.Ignore)]
    public string[] Relations { get; set; }
}

Modeling resources and collections is drop-dead simple:

// Resources are also (self-referential) links
public abstract class Resource : Link
{
    // Rewritten using LinkRewritingFilter during the response pipeline
    [JsonIgnore]
    public Link Self { get; set; }
}

// Collections are also resources
public class Collection : Resource
{
    public const string CollectionRelation = "collection";

    public T[] Value { get; set; }
}

These base classes make returning responses from the API nice and clean.

Basic API controllers and routing

API controllers in ASP.NET Core inherit from the Controller class and use attributes to define routes. The common pattern is naming the controller Controller, and using the /[controller] attribute value, which automatically names the route based on the controller name:

// Handles all routes under /comments
[Route("/[controller]")]
public class CommentsController : Controller
{
    // Action methods...
}

Methods in the controller handle specific HTTP verbs and sub-routes. Returning IActionResult gives you the flexibility to return both HTTP status codes and object payloads:

// Handles route:
// GET /comments
[HttpGet]
public async Task GetCommentsAsync(CancellationToken ct)
{
    return NotFound(); // 404
    
    return Ok(data); // 200 with JSON payload
}

// Handles route:
// GET /comments/{commentId}
// and {commentId} is bound to the argument in the method signature
[HttpGet("{commentId}"]
public async Task GetCommentByIdAsync(Guid commentId, CancellationToken ct)
{
    // ...
}

Named routes pattern

If you need to refer to specific routes later in code, you can use the Name property in the route attribute to provide a unique name. I like using nameof to name the routes with the same descriptive name as the method itself:

[HttpGet(Name = nameof(GetCommentsAsync))]
public async Task GetCommentsAsync(CancellationToken ct)
{
    // ...
}

This way, the compiler will make sure route names are always correct.

Async/await best practices

ASP.NET Core supports async/await all the way down the stack. Any controllers or services that make network or database calls should be async. Entity Framework Core provides async versions of database methods like SingleAsync and ToListAsync.

Adding a CancellationToken parameter to your route methods allows ASP.NET Core to notify your asynchronous tasks of a cancellation (if the browser closes a connection, for example).

Keep controllers lean

I like keeping controllers as lean as possible, by only concerning them with:

• Validating model binding (or not, see below!)
• Checking for null, returning early
• Orchestrating requests to services
• Returning nice results

Notice the lack of business logic! Keeping controllers lean makes them easier to test and maintain. Lean controllers fit nicely into more complex patterns like CQRS or Mediator as well.

Validate model binding with an ActionFilter

Most routes need to make sure the input values are valid before proceeding. This can be done in one line:

if (!ModelState.IsValid) return BadRequest(ModelState);

Instead of having this line at the top of every route method, you can factor it out to an ActionFilter which can be applied as an attribute:

[HttpGet(Name = nameof(GetCommentsAsync))]
[ValidateModel]
public async Task GetCommentsAsync(...)

The ModelState dictionary contains descriptive error messages (especially if the models are annotated with validation attributes). You could return all of the errors to the user, or traverse the dictionary to pull out the first error:

var firstErrorIfAny = modelState
    .FirstOrDefault(x => x.Value.Errors.Any())
    .Value?.Errors?.FirstOrDefault()?.ErrorMessage

Provide a root route

It's not HATEOAS unless the API has a clearly-defined entry point. The root document can be defined as a simple resource of links:

public class RootResource : Resource
{
    public Link Conversations { get; set; }

    public Link Comments { get; set; }
}

And returned from a controller bound to the / route:

[Route("/")]
public class RootController : Controller
{
    [HttpGet(Name = nameof(GetRoot))]
    public IActionResult GetRoot()
    {
        // return Ok(new RootResponse...)
    }
}

Serialize errors as JSON

A JSON API is expected to return exceptions or API errors as JSON. It's possible to write an exception filter that will serialize all MVC errors to JSON, but some errors occur outside of the MVC pipeline and won't be caught by an exception filter.

Instead, exception-handling middleware can be added in Startup.Configure:

var jsonExceptionMiddleware = new JsonExceptionMiddleware(
    app.ApplicationServices.GetRequiredService());
app.UseExceptionHandler(new ExceptionHandlerOptions { ExceptionHandler = jsonExceptionMiddleware.Invoke });

Passing IHostingEnvironment to the middleware makes it possible to send more detailed information during development, but send a generic error message in production. The middleware is implemented in JsonExceptionMiddleware.cs.

Generate absolute URLs automatically with a filter

The Controller base class provides an easy way to generate protocol- and server-aware absolute URLs with Url.Link(). However, if you need to generate these links outside of a controller (such as in service code), you either need to pass around the IUrlHelper or find another way.

In this project, the Link class represents an absolute link to another resource or collection. The derived RouteLink class can stand in (temporarily) as a placeholder that contains just a route name, and at the very end of the response pipeline the LinkRewritingFilter enerates the absolute URL. (Filters have access to IUrlHelper, just like controllers do!)

Map resources using AutoMapper

It's a good idea to keep the classes that represent database entitie