liveBook · Manning

Self-descriptive messages

As explained in Building Web APIs with ASP.NET Core

Self-descriptive messages contain all information required for a recipient to understand and process them correctly.

Self-descriptive messages contain everything the recipient needs to understand and process them correctly. In a web API, HTTP headers identify details such as the protocol version, method, content type, language, character set, and caching metadata. Requests and responses must set this information properly so clients and servers can interpret one another without relying on hidden context. section 1.1.4 section 3.1.6

A self-descriptive representation should make its intended processing clear:

  • Use JSON or another standard representation to describe the resource. section 3.1.6
  • Include information about the HTTP method, expected MIME type, and relevant metadata. section 3.1.6
  • Return descriptive links when clients need guidance about modifying a resource or requesting related resources. section 3.1.6

A board-game response

A board-games endpoint can wrap its data in a response containing a data array and a links array. Each link supplies an href, a relation such as self, and the HTTP type GET. The client therefore receives both the board games and information about how the response relates to the API. section 3.1.6

How Building Web APIs with ASP.NET Core covers it

How deep it goes
Explains the principle and implements it through JSON representations, HTTP headers, metadata, and descriptive links.
Examples
Uses a BoardGamesController response with board-game data, a self link, an href, a relation, and an HTTP method.
What you can do after
Apply it via HTTP headers and representations that tell clients how to interpret and navigate API responses.
How it connects
Connects REST, HTTP headers, JSON, MIME types, uniform interfaces, and HATEOAS.
Cover of Building Web APIs with ASP.NET Core
liveBookmanning.com
Read Building Web APIs with ASP.NET Core on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Building Web APIs with ASP.NET Core. The section links point to the parts of the book it draws on.