A uniform interface is the REST constraint that lets clients work with an API without knowing how the server is implemented. Resources have identifiable addresses, requests and responses explain themselves, and responses can point clients toward available next actions. This shared approach keeps clients and servers decoupled. section 1.1.4 section 3.1.6
Four principles guide a uniform interface:
- Identify each resource with a unique URI, such as /api/games/11 for one board game. section 1.1.4
- Manipulate resources through representations using the URI and an HTTP method: GET reads the game; DELETE removes it. section 1.1.4
- Make messages self-descriptive so recipients have the information needed to process them. HTTP headers supply metadata such as content type. section 1.1.4
- Provide hypermedia controls that help clients discover what they can do next, rather than requiring them to know every related action in advance. section 3.1.6 section 3.5
In ASP.NET Core, one practical approach is to return a response DTO containing both the requested data and structured links. A generic RestDTO<T> holds Data and a list of LinkDTO objects; each link carries an href, a relationship, and an HTTP method. This is an implementation choice, not a response format mandated by REST. section 3.1.6 section 3.5
A board-game collection response
A GET response for BoardGames can return an array of games under data and a self link under links. The link identifies the collection URL and marks GET as its method. Inspecting the JSON response confirms that the client receives both the games and a machine-readable way to revisit the collection; additional links could guide further requests. section 3.1.6
{
"data": [
{
"id": 1,
"name": "Axis & Allies",
"year": 1981
},
{
"id": 2,
"name": "Citadels",
"year": 2000
},
{
"id": 3,
"name": "Terraforming Mars",
"year": 2016
}
],
"links": [
{
"href": "https://localhost:40443/BoardGames",
"rel": "self",
"type": "GET"
}
]
}
Inspect the JSON response to see the data array alongside a link with href, rel, and type fields. section 3.1.6
A uniform interface takes more than choosing predictable URLs. Including structured links and metadata helps clients understand available actions and allows the API to evolve without tying clients as closely to its implementation. section 3.1.6 section 3.5
