In this article, we are going to talk about one of the most important concepts in building RESTful APIs – HATEOAS and learn how to implement HATEOAS in ASP.NET Core Web API. This article relies heavily on the concepts we’ve implemented so far in paging, filtering, searching, sorting articles, and especially data-shaping and builds upon foundations we’ve put down in these articles.

This article contains some advanced concepts of REST and Web API. If you find yourself lost or like you’re missing part of the whole picture, take a step back and take your time to go over these articles first. We’ll also link the relevant resource throughout the article if you want to explore some topics further.

You can find the source code on the GitHub repo. If you want to follow along with the article, you can use the start branch and if you want to get the final solution or if you get stuck, switch to the finished project.

NOTE: Some degree of previous knowledge is needed to follow this article. It relies heavily on the ASP.NET Core Web API series on Code Maze, so if you are not sure how to set up the database or how the underlying architecture works, we strongly suggest you go through the series.

In this article we are going to learn:

Let’s get into it.

What is HATEOAS and Why Is It so Important?

HATEOAS (Hypermedia as the Engine of Application State) is a very important REST constraint. Without it, a REST API cannot be considered RESTful and many of the benefits we get by implementing a REST architecture are unavailable.

Hypermedia refers to any kind of content that contains links to media types such as documents, images, videos…

REST architecture allows us to generate hypermedia links in our responses dynamically and thus make navigation much easier. To put this into perspective, think about a website that uses hyperlinks to help you navigate to different parts of it. You can achieve the same effect with HATEOAS in your REST API.

Imagine a website that has a home page and you land on it, but there are no links anywhere. You need to scrape the website or find some other way to navigate it to get to the content you want. We’re not saying that the website is the same as a REST API, but you get the point.

The power of being able to explore an API on your own can be very useful.

Let’s see how that actually works.

Typical Response with HATEOAS Implemented

Let’s say we want to get some Owners from our API.

But how do we do that?

We don’t even know how to get to the owners endpoint. Well first we would go to the only thing we know how to request and that’s the root of the application:


Our root endpoint should tell us more about our API, or rather where to start exploring it:

Ok, now we know what is available to us immediately and we can proceed to get existing owners:


And indeed we get the owners:

As you can see we got the list of our owners, and for each owner all the actions we can perform on them. And so on…

So, it’s a nice way to make an API self-discoverable and evolvable.

What is a Link?

According to RFC5988, a link is “a typed connection between two resources that are identified by Internationalised Resource Identifiers (IRIs)“. Simply put we use links to traverse the internet or rather the resources on the internet.

Our responses contain an array of Links, which consist of a few properties according to the RFC:

  • href – represents a target URI
  • rel – represents a link relation type, which means it describes how the current context is related to the target resource
  • method – we need an HTTP method to know how to distinguish the same target URIs

Pros/Cons of Implementing HATEOAS

So what are all the benefits we can expect when implementing HATEOAS?

HATEOAS is not trivial to implement, but the rewards we reap are worth it. Some of the things we can expect to get when we implement HATEOAS:

  • API becomes self-discoverable and explorable
  • A client can use the links to implement its logic, it becomes much easier, and any changes that happen in the API structure are directly reflected onto the client
  • The server drives the application state and URL structure and not vice versa
  • The link relations can be used to point to developer documentation
  • Versioning through hyperlinks becomes easier
  • Reduced invalid state transaction calls
  • API is evolvable without breaking all the clients

We can do so much with HATEOAS. But since it’s not easy to implement all these features, we should keep in mind the scope of our API and if we actually need all this. There is a great difference between a high volume public API and some internal API that is needed to communicate between parts of the same system.

As with everything else, the context is everything. Keep it simple.

That is more than enough theory for now. Let’s get to work and see how the concrete implementation of HATEOAS looks like.

Extending the Model in Preparation For HATEOAS Implementation

Let’s begin with the concept we know so far, and that’s the Link. First, we are going to create the Link entity in the Models folder of the Entities project:

Note that we have an empty constructor too. We’ll need that for XML serialization purposes, so keep it that way.

Next on, we need to create a class that will contain all of our links – LinkResourceBase:

And finally, since our response needs to describe the root of the controller, we need a wrapper for our Links:

This class might not make too much sense right now, but stay with us and it will become clear later down the road. For now, let’s just assume we wrapped our links in another class for the response representation purposes.

Since our response will contain links too now, we need to extend the XML serialization rules, so that our XML response returns the properly formatted links. Without this we would get something like: <Links>System.Collections.Generic.List`1[Entites.Models.Link]<Links>. So, we need to extend the WriteXmlElement method to support Links:

As we did in the data shaping article, we won’t go into too much detail here since it is out of the scope of the article, but the logic isn’t too complicated either. In short, we check if the type is List<Link>, and if it is, we iterate through all the links and call the method recursively to for each of the properties: href, method, and rel.

That’s all we need for now. We have a solid foundation to implement HATEOAS in our controllers.

Implementing HATEOAS in ASP.NET Core Web API

Now, let’s head towards our OwnerController and actually implement HATEOAS.

First, we need to extend our controller with the LinkGenerator class, which will help us build the links we want:

Next on, we need to extend our GetOwners method to add the relevant links to the returned owners:

We iterate through all the owners we’ve returned and added the relevant links to them. After that, we wrap the owners collection and create links that are important for the entire collection.

Now we just need the implementation for CreateLinksForOwner and CreateLinksForOwners methods:

There are a few things to note here.

We need to take the fields into consideration while creating the links since we might be using it in our requests. We are creating the links by using the LinkGenerator‘s GetUriByAction method which accepts HttpContext, the name of the action, and the values that need to be used to make the URL valid. In the case of the OwnersController, we send the owner id and fields.

The response which we expect is exactly as the one we’ve used as an example.

We are doing something similar to our GetOwnerById method:

The logic is much easier to implement for a single owner since we don’t need to wrap it.

We are going to do the same for the AccountController, but with a slight difference. As you know the endpoint to the AccountController is a bit different:


We need to take this into consideration while creating our HATEOAS links:

Our AccountController implementation doesn’t contain Create, Update or Delete methods so it’s much simpler, but, as you can see, in addition to the account id, we need to provide the owner id too, in order to properly generate links. We need to take fields into consideration in this case too.

So let’s quickly test our implementation and see how it works.

Testing Our Solution

Let’s begin with the simple query to our owners endpoint:
GET https://localhost:5001/api/owner

This should return the list of owners with the links attached:

As you can see, there are all the links we’ve defined for our owner. The whole collection of owners is wrapped in the “value” entity because right at the end we define a link that describes “self” or rather how to get to the controller. We can extend it anytime we want with other relevant links that are important to the controller.

That was the whole point of the wrapper we implemented.

Now let’s proceed by testing the single owner:
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906

This should result in:

Just one owner, no wrappers whatsoever.

Now, let’s try to get the accounts for that owner:
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account

We get the list of that owner’s accounts and links to them:

And finally let’s test a single account:
GET https://localhost:5001/api/owner/24fd81f8-d58a-4bcc-9f35-dc6cd5641906/account/371b93f2-f8c5-4a32-894a-fc672741aa5b

The result should be pretty obvious at this point:

One link, describing how to get to that account. As you can see, there are two ids in that link, so we’ve done a great job in our implementation.

Now, the only thing remaining to test is how it works when we select the fields we want:
GET https://localhost:5001/api/owner?fields=name

And much to our surprise, this doesn’t work.

Why is that?

Improving the Solution

Well, as you can see the HATEOAS implementation relies on having the ids available to construct the links for the response. Data shaping, on the other hand, enables us to return only the fields we want. And in our test scenario, we wanted just the names of the owners. That means we haven’t returned the ids of those owners and we cannot construct the target URIs now.

To solve this problem we want to make sure that id is always returned to the controller.

First, we’ll implement a wrapper named ShapedEntity which besides the entity contains the Id property:

Next on, we are going to replace all usages of the Entity class in the entire project with the ShapedEntity. The classes in which you need to replace every usage of the Entity class: AccountRepository, IAccountRepository, OwnerRepository, IOwnerRepository, DataShaper, and IDataShaper.

In addition to that, we need to extend the FetchDataForEntity method in the DataShaper class to get the id separately:

Now we have all we need to create the links no matter what properties we get using data shaping.

All that is left is to tweak our controller actions a bit:

The AccountController class gets the same treatment.

Now let’s try the same query again:
GET https://localhost:5001/api/owner?fields=name

And we get:

Great! That’s exactly what we wanted.

Introducing Custom Media Types

Now, returning HATEOAS links is a nice addition to our API. But as you can see the responses can be a bit lengthy and we purposely shortened a few of them to make the article more readable.

We want to give an API user the ability to do that, too.

And how can we do that?

The answer is by utilizing the power of custom media types.

We are going to create our own media types that we use when we want to return a response that includes HATEOAS links. If we don’t use it, the response won’t include any links and will be plain and simple like we’ve used to return it.

Before we start, let’s see how we can create a custom media type. A custom media type should look something like this: application/vnd.codemaze.hateoas+json. To compare it to the typical json media type which we use by default: application/json.

So let’s break down the different parts of a custom media type:

  • vnd – vendor prefix, it’s always there
  • codemaze – vendor identifier, we’ve chosen codemaze, because why not
  • hateoas – media type name
  • json – suffix, we can use it to describe if we want json or XML response for example

Now let’s implement that in our application.

Registering Custom Media Types

First, we want to register our new custom media types in the middleware. Otherwise, we’ll just get 406 Not Acceptable.

Let’s add a new extension method to our ServiceExtensions:

We are registering two new custom media types: application/vnd.codemaze.hateoas+json for our newtonSoftJsonSerializerOutputFormatter and application/vnd.codemaze.hateoas+xml for our xmlDataContractSerializerOutputFormatter. This will make sure we don’t get a 406 Not Acceptable response.

Add that to our Startup.cs in the ConfigureServices method, just after the AddControllers method:

That takes care of the custom media types registration.

Implementing a Media Type Validation Filter

Now, since we’ve implemented custom media types, we want our Accept header to be present in our requests so we can detect when the user requested the HATEOAS enriched response.

To do that, we’ll implement an ActionFilter which will validate our Accept header and media types:

We check for the existence of the Accept header first. If it’s not present we return BadRequest. If it is, we parse the media type, and if there is no valid media type present, we return BadRequest.

Once we’ve passed the validation checks, we pass the parsed media type to the HttpContext of the controller.

Don’t forget to register the filter in the IoC:

Now we need to decorate our GetOwners and GetOwnerById actions with [ServiceFilter(typeof(ValidateMediaTypeAttribute))] for these validations to take place.

As for the logic itself, we need to extend these actions a bit:

We read the media type we’ve parsed in the ValidateMediaTypeAttribute ActionFilter and cast it to MediaTypeHeaderValue type. Using the SubTypeWithoutSuffix.EndsWith of the MediaTypeHeaderValue class we check if HATEOAS is requested, and if it’s not we return owners immediately. If it is, we add the links and return them as we did before this implementation.

Same story with the GetOwnerById action:

Now to test this out, let’s try the simple request to get the owners with the Accept request header set to application/json:
GET https://localhost:5001/api/owner

We should get:

And now, when we change the Accept header to application/vnd.codemaze.hateoas+json and we should get:

Fantastic. Now we have the means to choose between the json, XML and HATEOAS responses as we please.

Let’s summarize.


HATEOAS is indeed one of the most useful but at the same one of the most complicated REST concepts to implement. How you implement HATEOAS in your API and how much you invest in polishing it is up to you. HATEOAS is easy “the one” thing that separates the excellent API from the just good or bad ones.

So what have we learned this time:

  • What HATEOAS is and how important it is in the RESTful world
  • How to implement HATEOAS in ASP.NET Core WebAPI project
  • Improved our solution to work nicely with data shaping
  • How to support XML serialization of dynamic objects with HATEOAS links
  • What custom media types are and how to utilize them to make HATEOAS optional in our responses

This article turned out to be pretty lengthy, but we hope you learned something new and once again if you found it hard to follow, check out our finished project, and compare and contrast to your own solution.