Hypermedia

A .NET Client and Server foundational Hypermedia library for .NET. Currently, there is only support for the JSON API format, but the foundation has been designed with extensibility in mind.

The packages are currently available via NuGet

Quick Start

Start with some domain/POCO objects. The Hypermedia model sits externally to the domain objects.

public class User
{
    public int Id { get; set; }
    public string DisplayName { get; set; }
    public int Reputation { get; set; }
    public string ProfileImageUrl { get; set; }
    public DateTimeOffset CreationDate { get; set; }
}

public class Post
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Body { get; set; }
    public int Score { get; set; }
    public DateTimeOffset CreationDate { get; set; }
    public int OwnerUserId { get; set; }
    public User OwnerUser { get; set; }
    public IReadOnlyList<Comment> Comments { get; set; }
}

public class Comment
{
    public int Id { get; set; }
    public string Text { get; set; }
    public DateTimeOffset CreationDate { get; set; }
    public int UserId { get; set; }
    public User User { get; set; }
    public int PostId { get; set; }
    public Post Post { get; set; }
}

Define your model using the Fluent builder interface.

static IContractResolver CreateResolver()
{
    return new Builder()
        .With<User>("users")
            .Id(nameof(User.Id))
            .Ignore(nameof(User.PasswordHash)
            .HasMany<Post>("posts")
                .Template("/v1/users/{id}/posts", "id", resource => resource.Id)
        .With<Post>("posts")
            .Id(nameof(Post.Id))
            .BelongsTo<User>(nameof(Post.OwnerUser))
                .BackingField(nameof(Post.OwnerUserId))
                .Template("/v1/users/{id}", "id", resource => resource.OwnerUserId)
            .HasMany<Comment>(nameof(Post.Comments))
                .Template("/v1/posts/{id}/comments", "id", resource => resource.Id)
        .With<Comment>("comments")
            .Id(nameof(Comment.Id))
            .BelongsTo<User>(nameof(Comment.User))
                .BackingField(nameof(Comment.UserId))
                .Template("/v1/users/{id}", "id", resource => resource.UserId)
            .BelongsTo<Post>(nameof(Comment.Post))
                .BackingField(nameof(Comment.PostId))
                .Template("/v1/posts/{id}", "id", resource => resource.PostId)
        .Build();
}

static void ConfigureFormatters(HttpConfiguration configuration)
{
    configuration.Formatters.Remove(configuration.Formatters.XmlFormatter);
    configuration.Formatters.Remove(configuration.Formatters.JsonFormatter);

    configuration.Formatters.Add(new JsonApiMediaTypeFormatter(CreateResolver()));
}

Client Extensions

The Hypermedia.JsonApi.Client package provides some extension methods to GET and POST/PUT/PATCH to and from JSON API compliant backends.

Returning a Single Resource

var response = await _httpClient.GetAsync($"v1/users/{id}", cancellationToken);
response.EnsureSuccessStatusCode();

return await response.Content.ReadAsJsonApiAsync<UserResource>(CreateResolver());

Returning a List of Resources

var response = await _httpClient.GetAsync($"v1/posts?skip={skip}&take={take}", cancellationToken);
response.EnsureSuccessStatusCode();

return await response.Content.ReadAsJsonApiManyAsync<PostResource>(_resourceContractResolver);

Samples

View the Hypermedia.Sample.WebApi project for an example of how to use the Hypermedia library. The sample API is running live at http://hypermedia.cainosullivan.com/ and has the following endpoints;

Try it out now.

http://hypermedia.cainosullivan.com/v1/posts/1?$prettify=true&$format=jsonapi