|
1 | | -[](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/ci-cd.yml) |
2 | | -[](https://github.com/intility/Intility.JsonApiToolkit/actions/workflows/docs.yml) |
3 | | - |
4 | | -# Intility.JsonApiToolkit |
5 | | - |
6 | | -JsonApiToolkit is a lightweight toolkit for implementing the [JSON:API specification](https://jsonapi.org/) in .NET applications. |
| 1 | +<h1 align="center"> |
| 2 | + <img src="https://avatars.githubusercontent.com/u/35199565" width="124px"/><br/> |
| 3 | + JsonApiToolkit |
| 4 | +</h1> |
| 5 | + |
| 6 | +<p align="center"> |
| 7 | + <em>A .NET toolkit for implementing the JSON:API specification.</em> |
| 8 | +</p> |
| 9 | +<p align="center"> |
| 10 | + <a href="https://dotnet.microsoft.com/"> |
| 11 | + <img src="https://img.shields.io/badge/.NET-10.0-blue.svg?logo=dotnet&logoColor=white&label=.NET" alt=".NET version"> |
| 12 | + </a> |
| 13 | + <a href="https://www.nuget.org/packages/Intility.JsonApiToolkit"> |
| 14 | + <img src="https://img.shields.io/nuget/v/Intility.JsonApiToolkit.svg?logo=nuget&logoColor=white&label=NuGet" alt="NuGet"> |
| 15 | + </a> |
| 16 | + <a href="https://jsonapi.org/"> |
| 17 | + <img src="https://img.shields.io/badge/JSON%3AAPI-1.1-blue.svg" alt="JSON:API version"> |
| 18 | + </a> |
| 19 | + <a href="https://github.com/intility/json-api-toolkit/blob/main/LICENSE"> |
| 20 | + <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"> |
| 21 | + </a> |
| 22 | + <a href="https://github.com/intility/json-api-toolkit/actions/workflows/ci-cd.yml"> |
| 23 | + <img src="https://github.com/intility/json-api-toolkit/actions/workflows/ci-cd.yml/badge.svg" alt="CI/CD"> |
| 24 | + </a> |
| 25 | +</p> |
| 26 | + |
| 27 | +## Description |
| 28 | + |
| 29 | +JsonApiToolkit makes ASP.NET Core APIs speak the [JSON:API specification](https://jsonapi.org/). It translates standard query parameters (`filter[]`, `sort`, `include`, `fields[]`, `page[]`) into typed EF Core queries and returns spec-compliant response documents, so your controllers stay short and predictable. |
7 | 30 |
|
8 | 31 | ## Installation |
9 | 32 |
|
10 | | -To install this package from Intility's GitHub Packages, add this to your NuGet.config file: |
11 | | - |
12 | | -```xml |
13 | | -<?xml version="1.0" encoding="utf-8"?> |
14 | | -<configuration> |
15 | | - <packageSources> |
16 | | - <add key="github" value="https://nuget.pkg.github.com/Intility/index.json" /> |
17 | | - </packageSources> |
18 | | - <packageSourceCredentials> |
19 | | - <github> |
20 | | - <add key="Username" value="YOUR_GITHUB_USERNAME" /> |
21 | | - <add key="ClearTextPassword" value="YOUR_GITHUB_PAT" /> |
22 | | - </github> |
23 | | - </packageSourceCredentials> |
24 | | -</configuration> |
25 | | -``` |
26 | | - |
27 | | -Then install the package via NuGet: |
28 | | - |
29 | 33 | ```bash |
30 | 34 | dotnet add package Intility.JsonApiToolkit |
31 | 35 | ``` |
32 | 36 |
|
33 | | -## Setup |
| 37 | +## Usage |
34 | 38 |
|
35 | | -1. **Register services:** |
36 | | - In your `Program.cs` or `Startup.cs`, add the toolkit services to your dependency injection container: |
| 39 | +Register the toolkit in `Program.cs`: |
37 | 40 |
|
38 | | - ```csharp |
39 | | - builder.Services.AddJsonApiToolkit(); |
40 | | - ``` |
41 | | - |
42 | | -2. **Inheritance:** |
43 | | - Derive your API controllers from the provided `JsonApiController` to leverage helper methods that return JSON:API compliant responses. |
| 41 | +```csharp |
| 42 | +builder.Services.AddJsonApiToolkit(); |
| 43 | +``` |
44 | 44 |
|
45 | | - ```csharp |
46 | | - public class BooksController : JsonApiController |
47 | | - { |
48 | | - // Your endpoint implementations here |
49 | | - } |
50 | | - ``` |
| 45 | +Derive controllers from `JsonApiController` and let `JsonApiQueryAsync` handle the request: |
51 | 46 |
|
52 | | -3. **Configuration:** |
53 | | - The toolkit automatically configures JSON serialization settings (camelCase properties, ignoring nulls, etc.) and adds the JSON:API media type to the supported output formatters. |
| 47 | +```csharp |
| 48 | +public class BooksController : JsonApiController |
| 49 | +{ |
| 50 | + [HttpGet] |
| 51 | + [AllowedIncludes("author", "publisher")] |
| 52 | + public Task<IActionResult> GetBooks() => |
| 53 | + JsonApiQueryAsync(_dbContext.Books.AsQueryable(), "book"); |
| 54 | +} |
| 55 | +``` |
54 | 56 |
|
55 | | -## GitHub Actions |
56 | | -To get fetch the package in your GitHub Actions workflow, add the following to your workflow file: |
| 57 | +Then call the endpoint with JSON:API query parameters: |
57 | 58 |
|
58 | | -```yaml |
59 | | -- name: Add Intility NuGet Package Source |
60 | | - run: | |
61 | | - dotnet nuget add source https://nuget.pkg.github.com/Intility/index.json \ |
62 | | - --name Intility \ |
63 | | - --username ${{ github.actor }} \ |
64 | | - --password ${{ secrets.GITHUB_TOKEN }} \ |
65 | | - --store-password-in-clear-text |
| 59 | +``` |
| 60 | +GET /api/books?filter[title]=javascript&include=author&fields[book]=title,published&page[size]=10&sort=-published |
66 | 61 | ``` |
67 | 62 |
|
68 | | -> [!IMPORTANT] |
69 | | -> Your Github token must have the `read:packages` scope to access the package. |
70 | | - |
71 | | -## Endpoint Example |
| 63 | +## What it provides |
72 | 64 |
|
73 | | -```csharp |
74 | | -// GET: api/books |
75 | | -[HttpGet] |
76 | | -public async Task<IActionResult> GetBooks() |
77 | | -{ |
78 | | - var query = _dbContext.Books.AsQueryable(); |
| 65 | +- **JSON:API documents** - compliant `data` / `included` / `meta` / `links` / `errors` envelope on every response |
| 66 | +- **Filtering** - `filter[field]=value` with operators, nested paths, and filtering on included resources |
| 67 | +- **Sorting** - `sort=field,-other` with multi-field and descending support |
| 68 | +- **Pagination** - `page[number]` / `page[size]` with link generation, total counts, and clamping |
| 69 | +- **Sparse fieldsets** - `fields[type]=a,b` to limit returned attributes per resource type |
| 70 | +- **Included resources** - `include=author,publisher.country` with allowlisting via `[AllowedIncludes]` |
| 71 | +- **EF Core integration** - query operators translate directly to SQL via `IQueryable` |
| 72 | +- **Strict mode** - return 404 for out-of-range pages and validate filter paths against allowed includes |
79 | 73 |
|
80 | | - // JsonApiQueryAsync applies filtering, sorting, includes, and pagination automatically. |
81 | | - return await JsonApiQueryAsync(query, "book"); |
82 | | -} |
83 | | -``` |
| 74 | +## Documentation |
84 | 75 |
|
85 | | -[More examples (WIP)](https://congenial-telegram-prep6vq.pages.github.io/docs/api-controller-examples.html) |
| 76 | +Full documentation is at <https://intility.github.io/json-api-toolkit/>. |
86 | 77 |
|
87 | | -## Documentation |
88 | | -For complete documentation and detailed usage instructions, please visit our |
89 | | -[documentation page.](https://intility.github.io/Intility.JsonApiToolkit/) |
0 commit comments