JsonApiFramework

JsonApiFramework is a fast, extensible, and portable .NET framework for the reading and writing of client-side and server-side JSON API documents based on the domain model of the hypermedia API resources.

Note Version 2.0 Breaking Change

Version 2.0 is a breaking change from version 1.X by deprecating the use of IResource. To fix remove all usages of the IResource interface when defining your service model.

Overview

JSON API is an excellent specification for building hypermedia (Level 3 REST API) APIs in JSON. Using this standard solves the problem of how to format your hypermedia API responses (server) as well as requests for creating, updating, and deleting resources (client) with JSON. Adopting this standard promotes standardized communication protocols between client applications and hypermedia API servers making development and consumption of the hypermedia API effortless.

JsonApiFramework implements the JSON API 1.0 version of the specification that enables .NET developers to work with JSON API documents at a high level using .NET objects. Therefore JsonApiFramework helps .NET developers focus on core application functionality rather than on protocol implementation.

JsonApiFramework is a framework where developers define a service model that represents the domain model of the resources produced and consumed by a hypermedia API server or client application either through explicit configuration and/or implicit conventions. With a service model developers can use a document context that represents a session with a JSON API document for reading and/or writing of various JSON API concepts such as resources, relationships, links, meta information, error objects, and JSON API version information encapsulated as high level CLR objects.

Benefits and Features

Never have to work with JSON directly, instead work with .NET CLR objects
Reading JSON API documents through a reader interface
Building and Writing JSON API documents through a fluent-style progressive builder interface for
- Resource object documents
- Resource Identifier object documents
- Error object documents
Automatic generation of JSON API standard hypermedia for
- Document links
- Resource relationships and links
Automatic conversion between JSON API resources and .NET CLR resources
Support for both client-side and server-side specific JSON API document building styles
Support for JSON API compound documents by
- Inclusion of related resources
- Circular resource references supported
- Automatic generation of resource linkage between related resources
Support for manual adding of resource linkage between related resources without needing to include related resources
Support for HATEOAS (Hypermedia as the Engine of Application State) for resource relationship and links inclusion or exclusion with lambda expression predicates
Support for complex types at the resource level
Support for sparse fieldsets for server-side document building
- Feature can be enabled or disabled as needed
Support for meta information at the document, resource, relationship, link, error, and JSON API version levels
Support for portable development with JsonApiFramework binaries compiled as .NET Standard 1.0 class libraries
- Targeting the .NET Standard 1.0 version maximizes the number of platforms the JsonApiFramework binaries can be used on, see the .NET Standard documentation for details
Fast reading and writing of JSON API documents
- Internally uses a specialized DOM (Document Object Model) tree representing the JSON API document in memory
- Internally uses compiled .NET expressions for fast conversion between JSON API and .NET CLR resources

Extreme high code quality with 2000+ unit tests. Production ready.

For further details, please check out the Wiki and .NET Core Samples

Usage examples

The following are some brief but concise usage examples to get an overall feel for how JsonApiFramework works both client-side and server-side of things. More usage examples will be found in the wiki and samples.

Assume the following for the usage examples:

// JsonApiFramework CLR Types
// --------------------------
// Document                    Represents a JSON API document.
// DocumentContext             Represents a session with a JSON API document.
// 
// Blogging CLR Types
// ------------------
// BloggingDocumentContext     Specialization of DocumentContext for blogging resource types.
// 
//                             Internally contains the service model (think metadata) of the
//                             blogging resource types with optional naming conventions to apply
//                             when converting between JSON API and .NET CLR resources.     
// 
// Blogging Relationships
// ----------------------
// Blog has "to-many" relationship to Article named "articles"
// 
// Article has "to-one" relationship to Person named "author"
// Article has "to-many" relationship to Comment named "comments"
// 
// Comment has "to-one" relationship to Person named "author"

public class Blog
{
    public long BlogId { get; set; }
    public string Name { get; set; }
}

public class Article
{
    public long ArticleId { get; set; }
    public string Title { get; set; }
    public string Text { get; set; }
}

public class Comment
{
    public long CommentId { get; set; }
    public string Body { get; set; }
}

public class Person
{
    public long PersonId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Twitter { get; set; }
}

Server-side document building example #1:

This example shows how a server-side Web API Controller could construct and return a JSON API document for the following GET request for an individual article:

GET http://example.com/articles/1

public class ArticlesController : ApiController
{
    [Route("articles/{id}")]
    public async Task<IHttpActionResult> GetAsync(string id)
    {
        Contract.Requires(String.IsNullOrWhitespace(id) == false);

        // Get article /////////////////////////////////////////////////////
        var article = await GetArticle(id);

        // Build and return JSON API document ////////////////////////////// 
        var currentRequestUrl = HttpContext.Current.Request.Url;
        using (var documentContext = new BloggingDocumentContext())
        {
            // Build new document.
            var document = documentContext
                .NewDocument(currentRequestUrl)

                    // Document links
                    .Links()
                        .AddUpLink()
                        .AddSelfLink()
                    .LinksEnd()

                    // Resource document (convert CLR Article resource to JSON API resource)
                    .Resource(article)
                        // Article relationships
                        .Relationships()
                            // article -> author
                            .Relationship("author")
                                .Links()
                                    .AddSelfLink()
                                    .AddRelatedLink()
                                .LinksEnd()
                            .RelationshipEnd()

                            // article -> comments
                            .Relationship("comments")
                                .Links()
                                    .AddSelfLink()
                                    .AddRelatedLink()
                                .LinksEnd()
                            .RelationshipEnd()
                        .RelationshipsEnd()

                        // Article links
                        .Links()
                            .AddSelfLink()
                        .LinksEnd()
                    .ResourceEnd()

                .WriteDocument();

            // Return 200 OK
            // Note: WebApi JsonMediaTypeFormatter serializes the JSON API document into JSON. 
            return this.Ok(document);
        }
    }
}