DEV Community: Petar Radošević

Composing and nesting with JsonApiDotNetCore

Petar Radošević — Mon, 21 Dec 2020 10:00:23 +0000

This is the final part of my three-part series on the release of JsonApiDotNetCore 4.0! In our first post I showed you how to setup your API and in the second post I added relationships to the mix.

In this final post, lets dive deep and see some of the latest additions to the framework and what's coming next.

Filters

One of the powerful new additions to the framework is the ability to have composable filters. Lets say we want to have all todo-items with a priority lower than 2. We can get those with the following request:

GET /todoItems?filter=lessThan(priority,'2')

{
  "links": {
    "self": "https://localhost:5001/todoItems?filter=lessThan(priority,'2')",
    "first": "https://localhost:5001/todoItems?filter=lessThan(priority,'2')"
  },
  "data": [
    {
      "type": "todoItems",
      "id": "1",
      "attributes": {
        "todo": "Make pizza",
        "priority": 1
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/1/relationships/owner",
            "related": "https://localhost:5001/todoItems/1/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/1"
      }
    }
  ]
}

Previously I showed you how to include related resources, and the nice thing is, you can even apply filters on those! Lets see how we can get all people, along with their todo-items of first priority.

First, we need to include the related todoItems. Now we can apply the filter with the following request:

GET /people?include=todoItems&filter[todoItems]=equals(priority,'1').

This will give us the following payload, where we only see the todo-items with a priority of one.

{
  "links": {
    "self": "https://localhost:5001/people?include=todoItems&filter[todoItems]=equals(priority,'1')",
    "first": "https://localhost:5001/people?include=todoItems&filter[todoItems]=equals(priority,'1')"
  },
  "data": [...],
  "included": [
    {
      "type": "todoItems",
      "id": "1",
      "attributes": {
        "todo": "Make pizza",
        "priority": 1
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/1/relationships/owner",
            "related": "https://localhost:5001/todoItems/1/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/1"
      }
    }
  ]
}

We have now seen lessThan and equals, but there are more operators you can apply, like contains, any and even not to negate the filter. For a complete list, you can read the filtering chapter in the documentation.

It becomes even more powerful when we combine multiple conditions together. If we wanted to have all todo's from people whose name starts with John and have a priority of one, we can make the following request:

GET /todoItems?filter=and(startsWith(owner.name,'John'),equals(priority,'1'))

All of the above is being translated to SQL and nothing is being evaluated in memory! This is done by building up a tree of expressions which are then translated into a LINQ query.

You can read more of the work behind the scenes in this PR. Magic...

Finally, the filtering on related resources is not only available on filters, but you get those as well for pagination, sorting and even sparse fieldsets. We could go crazy with a request like the following:

GET /api/v1/blogs?include=articles.comments&page[number]=2,articles:3,articles.comments:4&page[size]=10,articles:5

This returns at most 10 blogs at page 2. Per blog, it returns at most 5 included articles, all at page 3. Per blog, per article, returns included comments at page 4 using default page size. Mind blown yet?

Conclusion

Although this blog series may have ended, the development on JsonApiDotNetCore has not.

Before I let you go, I would like to highlight an exciting new development called "Atomic Operations". This will allow you to send multiple changes, as a transaction, in a single request (on the streets people may call it batching) and thus reduce the amount of requests for making changes.

It's so powerful that it even allows you to establish relationships between operations within a single request, using something called local IDs. Work is progressing quickly on the atomic-operations branch. Check it out on Github if you want to follow along.

I hope you are as excited about JsonApiDotNetCore as I am!

There is still a lot more to explore, for example check out the configuration options, how you can create or update resources with relationships or the amount of extensibility you have at your proposal.

The 4.0 release is an amazing release which will delight all API clients out there. If you have any more questions, join the team on the Gitter community or start contributing on Github. And of course, you can reach out to me personally on Twitter under @wunki.

Happy RESTing!

Relationships with JsonApiDotNetCore

Petar Radošević — Mon, 21 Dec 2020 09:54:15 +0000

In our previous post we setup a basic JSON:API compliant API with the 4.0 release of the JsonApiDotNetCore framework. You can find the code we wrote under the part-1 branch on Github.

In this post I would like to introduce some of the more powerful capabilities of the framework and to do so, let's talk about relationships.

Relationships

We are going to use the canonical todo example and create the ability to assign a todo to a single person. Lets start by creating a new TodoItem.cs file and add the following to it:

using JsonApiDotNetCore.Resources;
using JsonApiDotNetCore.Resources.Annotations;

namespace MyApi
{
    public class TodoItem : Identifiable
    {
        [Attr]
        public string Todo { get; set; }

        [Attr]
        public uint Priority { get; set; }

        [HasOne]
        public Person Owner { get; set; }
    }
}

In the code above, we state that a TodoItem has a single Person as its owner. Let's also add the reverse relationship, where we state that a Person can have many todo's. Open up your Person.cs and add the following:

using System.Collections.Generic;
using JsonApiDotNetCore.Resources;
using JsonApiDotNetCore.Resources.Annotations;

namespace MyApi
{
    public class Person : Identifiable
    {
        [Attr]
        public string Name { get; set; }

        [HasMany]
        public ICollection<TodoItem> TodoItems { get; set; }
    }
}

We're also going to add our new TodoItem to our DbContext to release the power of Entity Framework Core:

using Microsoft.EntityFrameworkCore;

namespace MyApi
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options)
            : base(options) { }

        public DbSet<Person> People { get; set; }
        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

To expose the new endpoint, let's create a controller, TodoItemsController.cs with the following boilerplate:

using JsonApiDotNetCore.Configuration;
using JsonApiDotNetCore.Controllers;
using JsonApiDotNetCore.Services;
using Microsoft.Extensions.Logging;

namespace MyApi.Controllers
{
    public class TodoItemsController : JsonApiController<TodoItem>
    {
        public TodoItemsController(
                IJsonApiOptions options,
                ILoggerFactory loggerFactory,
                IResourceService<TodoItem> resourceService)
            : base(options, loggerFactory, resourceService)
        { }
    }
}

Before we run our API, make sure to delete the my-api.db file in our project folder for it to pick up the new schema.

We can now run our API and go to https://localhost:5001/todoItems and we will see the following:

{
  "links": {
    "self": "https://localhost:5001/todoItems",
    "first": "https://localhost:5001/todoItems"
  },
  "data": []
}

It works, but it's a bit boring. Let's add some more data in our Startup.cs file:

if (!context.People.Any())
{
    context.People.Add(new Person
    {
        Name = "John Doe",
        TodoItems = new List<TodoItem>
        {
            new TodoItem { Todo = "Make pizza", Priority = 1},
            new TodoItem { Todo = "Clean room", Priority = 2}
        }
     });
     context.SaveChanges();
}

Another query will show us the following, if we go to /people we will see:

{
  "links": {
    "self": "https://localhost:5001/people",
    "first": "https://localhost:5001/people"
  },
  "data": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "name": "John Doe"
      },
      "relationships": {
        "todoItems": {
          "links": {
            "self": "https://localhost:5001/people/1/relationships/todoItems",
            "related": "https://localhost:5001/people/1/todoItems"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/people/1"
      }
    }
  ]
}

And if we query /todoItems we see:

{
  "links": {
    "self": "https://localhost:5001/todoItems",
    "first": "https://localhost:5001/todoItems"
  },
  "data": [
    {
      "type": "todoItems",
      "id": "1",
      "attributes": {
        "todo": "Make pizza",
        "priority": 1
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/1/relationships/owner",
            "related": "https://localhost:5001/todoItems/1/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/1"
      }
    },
    {
      "type": "todoItems",
      "id": "2",
      "attributes": {
        "todo": "Clean room",
        "priority": 2
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/2/relationships/owner",
            "related": "https://localhost:5001/todoItems/2/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/2"
      }
    }
  ]
}

Ok, if you thought this was cool, wait till you see the querying and filtering capabilities.

Including Relationships

To get all todo-items for a single person, the JSON:API spec defines a relationships endpoint, which would be /people/1/relationships/todoItems:

{
  "links": {
    "self": "https://localhost:5001/people/1/relationships/todoItems",
    "related": "https://localhost:5001/people/1/todoItems",
    "first": "https://localhost:5001/people/1/relationships/todoItems"
  },
  "data": [
    {
      "type": "todoItems",
      "id": "1"
    }
  ]
}

This shows you all the todo-items IDs for that specific person. To get all individual todo's would cost many queries.

Amazingly, JSON:API also enables you to get all that data in a single call, by doing:

GET /people/1?include=todoItems

{
  "links": {
    "self": "https://localhost:5001/people/1?include=todoItems"
  },
  "data": {
    "type": "people",
    "id": "1",
    "attributes": {
      "name": "John Doe"
    },
    "relationships": {
      "todoItems": {
        "links": {
          "self": "https://localhost:5001/people/1/relationships/todoItems",
          "related": "https://localhost:5001/people/1/todoItems"
        },
        "data": [
          {
            "type": "todoItems",
            "id": "1"
          },
          {
            "type": "todoItems",
            "id": "2"
          }
        ]
      }
    },
    "links": {
      "self": "https://localhost:5001/people/1"
    }
  },
  "included": [
    {
      "type": "todoItems",
      "id": "1",
      "attributes": {
        "todo": "Make pizza",
        "priority": 1
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/1/relationships/owner",
            "related": "https://localhost:5001/todoItems/1/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/1"
      }
    },
    {
      "type": "todoItems",
      "id": "2",
      "attributes": {
        "todo": "Clean room",
        "priority": 2
      },
      "relationships": {
        "owner": {
          "links": {
            "self": "https://localhost:5001/todoItems/2/relationships/owner",
            "related": "https://localhost:5001/todoItems/2/owner"
          }
        }
      },
      "links": {
        "self": "https://localhost:5001/todoItems/2"
      }
    }
  ]
}

OK, that was easy. But what if that's just too big of a payload and you do not want to waste any bandwidth? That's where "sparse fieldsets" come in.

You just want to show a list of the todo's? Let's reduce the payload:

GET /people/1?include=todoItems&fields[todoItems]=todo

{
  ...
  "included": [
    {
      "type": "todoItems",
      "id": "1",
      "attributes": {
        "todo": "Make pizza"
      },
      "links": {
        "self": "https://localhost:5001/todoItems/1"
      }
    },
    {
      "type": "todoItems",
      "id": "2",
      "attributes": {
        "todo": "Clean room"
      },
      "links": {
        "self": "https://localhost:5001/todoItems/2"
      }
    }
  ]
}

Pretty powerful stuff! But there is even more. In the next post, I want to show you some of the powerful filter capabilities that are also added in the 4.0 release.

Ow, and BTW, you can find all the code above in the part-2 branch on Github.

Unleash the power of REST with JsonApiDotNetCore

Petar Radošević — Mon, 21 Dec 2020 09:50:07 +0000

Reason for celebration, after two years of development, there is another major release of JsonApiDotNetCore (JADNC), the 4.0 release.

This release packs a lot of powerful features backed by 1000+ tests! To show off the amazing work by the team, I decided to write a three-part blog series where I'll demo its ease of use and capabilities by building a new API.

But before we start, let me convince you why you should still use JSON:API and don't need to go to GraphQL for that powerful API.

Levels

REST APIs come in levels and as developers like to do, it starts counting at 0.

Level 0 means it's using HTTP as the transport layer for remote communications. That's it.

Level 1 is where we add resources. Instead of talking to a single endpoint, let's say /api, you get multiple endpoints, /pizzas and /pastas.

Level 2 is when we add verbs. Communicate your intent on the resource by using HTTP verbs. Use GET when you know it is a read operation — does not make changes on the server — and POST when you want to change state.

In the final level, Level 3, the server adds URIs to the response which tell the client where to go if they want more information.

For some time the software industry has been releasing level 3 APIs and created specifications which guide you on the best practices. The most popular specification is the JSON:API specification, which you could guess, is used by us.

I also need to address another giant in this space. In 2015, Facebook released GraphQL to solve problems they experienced with the shift to mobile. GraphQL reduced the amount of network bandwith you need by its query capabilities. You can combine multiple requests into one, and get back the exact payload you need.

The downside of GraphQL was that it stepped away from some of the best practices on the web 👎.

You don't get Level 1 capabilities, where we have multiple endpoints, or Level 2, where we use HTTP verbs to communicate your intent.

Although GraphQL can use HTTP as a transport, it always uses a single endpoint. This means that decades of hardware and software and their caching solutions on top of HTTP standards can't cache GraphQL queries easily.

However! The communities' embrace of GraphQL showed us that people are happy to make these sacrifices for the increase in power they gained as consumers of APIs. Being able to reduce the amount of requests by introducing powerful query capabilities is an amazing thing to have.

In part 2 and 3 of this series we will show you how JSON:API gives you those capabilities, without loosing some of the benefits of REST. Before we do that, let's first cover the basics and get a project up and running.

Getting started with JSON:API

Let's start with creating a web project and installing the JsonApiDotNetCore library:

dotnet new webapi -o MyApi
cd MyApi
dotnet add package JsonApiDotnetCore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite

You can run the project with dotnet run and a webserver will spin up and be available at https://localhost:5000. It won't serve anything useful, for that we need to add models.

Let's add our first model by creating a Person.cs file and adding a Person:

using JsonApiDotNetCore.Resources;
using JsonApiDotNetCore.Resources.Annotations;

namespace MyApi
{
    public class Person : Identifiable
    {
        [Attr]
        public string Name { get; set; }
    }
}

There are two important things to note here. First we make Person implement the IIdentifiable<TId> interface by inheriting from Identifiable. This assumes our model has a unique key called Id with integer values.

Next step is adding Entity Framework Core to the mix.

Entity Framework Core

Entity Framework Core is a powerful ORM developed by Microsoft and JsonApiDotNetCore makes good use of it. To add the database as a storage mechanism for our model we need to create a new AppDbContext.cs file with the following:

using Microsoft.EntityFrameworkCore;

namespace MyApi
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options)
            : base(options) { }

        public DbSet<Person> People { get; set; }
    }
}

The DbSet is used to be able to query and save the Person model to the database.

Finally, we need to wire up the endpoint by creating a controller. When we ran dotnet new webapi -o MyApi, it created a controller and a model for us. Let's delete those two files as we won't need them.

rm WeatherForcast.cs
rm Controllers/WeatherForecastController.cs

And create a new controller in Controllers/PeopleController.cs.

using JsonApiDotNetCore.Configuration;
using JsonApiDotNetCore.Controllers;
using JsonApiDotNetCore.Services;
using Microsoft.Extensions.Logging;

namespace MyApi.Controllers
{
    public class PeopleController : JsonApiController<Person>
    {
        public PeopleController(
                IJsonApiOptions options,
                ILoggerFactory loggerFactory,
                IResourceService<Person> resourceService)
            : base(options, loggerFactory, resourceService)
        { }
    }
}

In the above code we see that the method receives IJsonApiOptions. It provides global options you can set in your application startup and lets you configure things like JSON casing and if clients are allowed to generate their own IDs.

Second we see the IResourceService, which hooks up the API to the persistence layer of the model.

To tie it all together we can enable JsonApiDotNetCore during startup of the project. Go to your Startup.cs file and replace ConfigureServices with the following:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // Add the Entity Framework Core DbContext like you normally would
    services.AddDbContext<AppDbContext>(options =>
    {
        // Use whatever provider you want, this is just an example
        options.UseSqlite("Data Source=my-api.db");
    });

    // Add JsonApiDotNetCore
    services.AddJsonApi<AppDbContext>();
}

This uses the AppDbContext we created earlier and uses SQLite as our database. Entity Framework Core supports MS SQL Server, SQLite, PostgreSQL, MySQL and Cosmos DB out of the box.

Finally, let's replace the default Configure method as well in our Startup.cs file with the following:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, AppDbContext context)
{
    context.Database.EnsureCreated();

    if (!context.People.Any())
    {
        context.People.Add(new Person
        {
             Name = "John Doe"
        });
        context.SaveChanges();
     }

     app.UseHttpsRedirection();
     app.UseRouting();
     app.UseJsonApi();
     app.UseEndpoints(endpoints => endpoints.MapControllers());
}

The UseJsonApi installs middleware for handling the incoming requests.

This is everything that is required to have a JSON:API, let's give it a run with dotnet run and send a request:

curl -k [https://localhost:5001/people](https://localhost:5001/people) | jq

This returns a 200 OK with a beautiful payload:

{
  "links": {
    "self": "https://localhost:5001/people",
    "first": "https://localhost:5001/people"
  },
  "data": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "name": "John Doe"
      },
      "links": {
        "self": "https://localhost:5001/people/1"
      }
    }
  ]
}

What's next

This is all that's needed to get a JSON:API up and running. You can find all the code of this part on Github under the part-1 branch.

In our next post I'll explore the power of relationships and how JSON API can reduce the amount of requests we need to make to get the data we need.