Hypermedia lets a response tell a client what it can do next. In a RESTful API, this is the HATEOAS constraint: clients follow descriptive links supplied by the server instead of needing to know every resource URI in advance. That separation lets server functionality evolve with less dependence on client-side knowledge. section 1.1.4
A board-game list that returns only game objects leaves clients to discover related actions elsewhere. To adopt a uniform interface, return the requested data alongside links that describe available requests. Links for changing resources should reflect what the client is permitted to do. section 3.1.6
One ASP.NET Core implementation uses two response types:
- LinkDTO holds an href, a relationship (rel), and a type. In the example, the type is the HTTP method GET. section 3.1.6
- RestDTO<T> wraps the requested Data and a list of Links. The controller's Get() action returns RestDTO<BoardGame[]> and creates a “self” link using Url.Action and the request scheme. section 3.1.6
public RestDTO<BoardGame[]> Get() #1
{
return new RestDTO<BoardGame[]>() #2
{
Data = new BoardGame[] {
new BoardGame() {
Id = 1,
Name = "Axis & Allies",
Year = 1981
},
new BoardGame() {
Id = 2,
Name = "Citadels",
Year = 2000
},
new BoardGame() {
Id = 3,
Name = "Terraforming Mars",
Year = 2016
}
},
Links = new List<LinkDTO> { #3
new LinkDTO(
Url.Action(null, "BoardGames", null, Request.Scheme)!,
"self",
"GET"),
}
};
}
The controller listing shows where the board-game array and its generated “self” link enter the same response. section 3.1.6
Check the response
Request the BoardGames endpoint and inspect the JSON. It contains a data array with three games and a links array whose “self” entry gives an href and GET method. This first link demonstrates the response shape; it does not yet show links for modifying games. section 3.1.6
