MinApiLib.Hypermedia 11.0.0

dotnet add package MinApiLib.Hypermedia --version 11.0.0
                    
NuGet\Install-Package MinApiLib.Hypermedia -Version 11.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MinApiLib.Hypermedia" Version="11.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MinApiLib.Hypermedia" Version="11.0.0" />
                    
Directory.Packages.props
<PackageReference Include="MinApiLib.Hypermedia" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MinApiLib.Hypermedia --version 11.0.0
                    
#r "nuget: MinApiLib.Hypermedia, 11.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MinApiLib.Hypermedia@11.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MinApiLib.Hypermedia&version=11.0.0
                    
Install as a Cake Addin
#tool nuget:?package=MinApiLib.Hypermedia&version=11.0.0
                    
Install as a Cake Tool

license version

MinApiLib.Hypermedia

Add links to responses when the client asks for them with the Accept header. Other clients keep receiving the plain response.

Installation

dotnet add package MinApiLib.Hypermedia

Usage

Register the services and apply the filter:

global using MinApiLib.Hypermedia;
// ...
builder.Services.AddHypermedia();
// ...
app.MapEndpoints()
   .WithHypermedia();

Create a provider for each response type. AddHypermedia() finds them in the calling assembly and registers them as scoped services, so they can inject dependencies:

public record struct Response(int Id, string Name);

public class ResponseHypermediaProvider : HypermediaProvider<Response>
{
    protected override IEnumerable<HypermediaLink> GetLinksFor(Response @object)
    {
        yield return new HypermediaLink("self", "/things/" + @object.Id, "GET");
        yield return new HypermediaLink("update", "/things/" + @object.Id, "PUT");
        yield return new HypermediaLink("delete", "/things/" + @object.Id, "DELETE");
        yield return new HypermediaLink("things", "/things", "GET");
    }
}

public record struct Request([FromRoute] int Id);

public record GetThing() : GetHandler<Request>("/things/{id}")
{
    protected override IResult Handle(Request request)
        => Results.Ok(new Response(request.Id, "John Doe"));
}

Send the hypermedia type in the Accept header to get the links:

$ curl -H "Accept: application/vnd.hypermedia+json" "http://localhost:5000/things/1"
{"value":{"id":1,"name":"John Doe"},"links":[{"href":"http://localhost:5000/things/1","rel":"self","method":"GET"},{"href":"http://localhost:5000/things/1","rel":"update","method":"PUT"},{"href":"http://localhost:5000/things/1","rel":"delete","method":"DELETE"},{"href":"http://localhost:5000/things","rel":"things","method":"GET"}]}

Configuration

To use another media type, or to scan another assembly:

builder.Services.AddHypermedia(typeof(Response).Assembly, contentType: "application/vnd.my.format+json");

To enable links only on some endpoints, skip the call on the group and apply the filter in each one:

protected override RouteHandlerBuilder Configure(RouteHandlerBuilder builder)
    => builder.WithHypermedia();

Behavior

  • The response uses the hypermedia content type only when the Accept header lists it, including in a list of types. A q=0 excludes it.
  • Links are added to successful responses with a value, from any handler: Results.Ok, Results.Created, Results.Json, or a typed TResponse. Status code and headers such as Location are kept.
  • Responses without a value, error responses, and values without a matching provider are returned unchanged. The client gets the plain value, with no error.
  • Relative links are completed with the request scheme, host and path base. Absolute http and https links are kept as they are.
  • Endpoints with the filter send Vary: Accept, so caches don't mix both representations.

Matching providers

A provider matches with an is T check on the returned value, and the first match wins. So a provider of a base class also applies to its derived classes: don't derive a response from another one that has a provider of its own.

For a list, use the interface:

public class ItemsHypermediaProvider : HypermediaProvider<IEnumerable<ResponseItem>>
{
    protected override IEnumerable<HypermediaLink> GetLinksFor(IEnumerable<ResponseItem> @object)
    {
        yield return new HypermediaLink("self", "/things", "GET");
    }
}

OpenAPI

ProducesHypermedia<T>() declares the wrapped response in the endpoint metadata, with the configured content type:

builder
    .ProducesHypermedia<Response>(StatusCodes.Status200OK)
    .Produces<Response>(StatusCodes.Status200OK);

ApiExplorer keeps one declaration per status code and the last one wins, so in this example the OpenAPI document shows only the plain Response. Documenting both representations requires a transformer or filter in your OpenAPI generator.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net11.0

    • No dependencies.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
11.0.0 89 11/10/2026
10.0.1 809 9/14/2026
10.0.0 696 11/19/2025
9.0.0 274 11/13/2024
8.0.1 278 4/11/2024
8.0.0 3,154 12/14/2023
7.0.4 2,252 5/17/2023
7.0.3 366 4/18/2023
7.0.2 440 3/22/2023
7.0.1 405 3/21/2023
7.0.0 447 2/14/2023
7.0.0-beta 385 11/10/2022