This week showed the release of JsonApiDotNetCore 4.0 (JADNC). A powerful framework implementing the JSON:API specification on .NET Core and .NET 5.
This release comes with an array of powerful features backed by 1000+ tests.
To show off the amazing work of the team, I have written a three-part blog series which demos its capabilities by building a new API . In this series we will talk about:
But before we go there, let my try and convince you why you should use JSON:API and REST for building your API.
REST APIs come in levels and as developers, we start counting at 0.
Level 0 for a REST API 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.
Before we dive in, I feel we 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.
We don't get Level 1 capabilities, where we have multiple endpoints, or Level 2, where we use HTTP verbs to communicate our intent. Although GraphQL can be transported over HTTP, it always uses a single endpoint. This means that decades of hardware and software with their caching solutions on top of HTTP standards can't cache GraphQL queries easily anymore.
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 powerful query capabilities is an amazing thing to have.
In part 2 and 3 of this post I will show you how JSON:API gives you these capabilities, without loosing some of the benefits of REST. Before I do that, let's first cover the basics and get a project up and running.