by nbarbettini

nbarbettini / BeautifulRestApi

Beautiful REST API design with ASP.NET Core and Ion

482 Stars 120 Forks Last release: Not found Apache License 2.0 79 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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 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 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
  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!

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

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

// DbSets...


The only difference between this and a "normal"

is the addition of a constructor that takes a
parameter. This is required by the in-memory provider.

Then, wire up the in-memory provider in

services.AddDbContext(options =>
    // Use an in-memory database with a randomized database name (for testing)

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

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

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!


Model Ion links, resources, and collections

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)]
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
    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

class and use attributes to define routes. The common pattern is naming the controller
, and using the
attribute value, which automatically names the route based on the controller name:
// Handles all routes under /comments
public class CommentsController : Controller
    // Action methods...

Methods in the controller handle specific HTTP verbs and sub-routes. Returning

gives you the flexibility to return both HTTP status codes and object payloads:
// Handles route:
// GET /comments
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

property in the route attribute to provide a unique name. I like using
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

. Entity Framework Core provides async versions of database methods like

Adding a

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))]
public async Task GetCommentsAsync(...)


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())

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

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

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


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


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

In this project, the

class represents an absolute link to another resource or collection. The derived
class can stand in (temporarily) as a placeholder that contains just a route name, and at the very end of the response pipeline the
enerates the absolute URL. (Filters have access to

, just like controllers do!)

Map resources using AutoMapper

It's a good idea to keep the classes that represent database entities separate from the classes that model what is returned to the client. (In this project, for example, the

class contains an

and other properties that aren't directly exposed to the client in

A object mapping library like AutoMapper saves you from manually mapping properties from entity classes to resource classes. AutoMapper integrates with ASP.NET Core easily with the AutoMapper.Extensions.Microsoft.DependencyInjection package and a

line in
. Most properties are mapped automatically, and you can define a mapping profile for custom cases.

AutoMapper plays nice with Entity Framework Core and async LINQ, too:

var items = await query // of CommentEntity
    .ProjectTo() // lazy mapping!
    .ToArrayAsync(ct); // of CommentResource

Use strongly-typed route parameter classes

If you look at the AutoMapper mapping profile from above, you'll notice that strongly-typed route values are saved in each Link:

    new GetConversationByIdParameters { ConversationId = src.Id })

(You'll also notice a practical use of the named routes pattern!)

When the URL of the link is generated (later), the provided route values are matched up with the route method definition. The

property is just an
, so you could pass an anonymous object instead:
    new { conversationId = src.Id })

However, defining a simple POCO makes this type-safe and foolproof:

public class GetConversationByIdParameters
    public Guid ConversationId { get; set; }

Instead of defining the parameters directly in the method signature, like this:

[HttpGet("{conversationId}", Name = nameof(GetConversationByIdAsync))]
public async Task GetConversationByIdAsync(
    Guid conversationId,
    CancellationToken ct)

The method signature contains the POCO itself:

[HttpGet("{conversationId}", Name = nameof(GetConversationByIdAsync))]
public async Task GetConversationByIdAsync(
    GetConversationByIdParameters parameters,
    CancellationToken ct)

Consume application configuration in services

ASP.NET Core comes with a powerful configuration system that you can use to provide dynamic configuration data to your API. You can define a group of properties in

"DefaultPagingOptions": {
  "limit": 25,
  "offset": 0

And bind that group to a POCO in


This places the POCO in the services (DI) container as a singleton wrapped in

, which can be injected in controllers and services:
private readonly PagingOptions _defaultPagingOptions;

public CommentsController( ICommentService commentService, IOptions defaultPagingOptionsAccessor) { // ... _defaultPagingOptions = defaultPagingOptionsAccessor.Value; }

Add paging to collections

Collections with more than a few dozen items start to become heavy to send over the wire. By enriching the

class with paging metadata, the client can get a paged collection experience complete with HATEOAS navigation links:

    "href": "",
    "rel": [ "collection" ],
    "offset": 0,
    "limit": 25,
    "size": 200,
    "first": { "href": "", "rel": [ "collection" ] },
    "next": { "href": "", "rel": [ "collection" ] },
    "last": { "href": "", "rel": [ "collection"] },
    "value": [

In this project, the

class handles the logic and math behind the scenes. Controllers that return collections accept a

[FromQuery] PagingOptions
parameter that binds to the
parameters needed for paging.

Paging using a limit and offset is a stateless approach to paging. You could implement paging statefully (using a cursor) instead by saving a cursor position in the database.

More to come...

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.