Skip to content

Commit 7e78030

Browse files
bkoelmanbkoelman
committed
Documentation updates
1 parent acf426d commit 7e78030

File tree

8 files changed

+191
-78
lines changed

8 files changed

+191
-78
lines changed

‎LICENSE

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
Copyright (c) 2017 Jared Nance
2+
Copyright (c) 2020 Bart Koelman
23

34
MIT License
45

‎PackageReadme.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
A framework for building [JSON:API](https://jsonapi.org/) compliant REST APIs using .NET Core and Entity Framework Core. Includes support for [Atomic Operations](https://jsonapi.org/ext/atomic/).
1+
A framework for building [JSON:API](https://jsonapi.org/) compliant REST APIs using ASP.NET Core and Entity Framework Core. Includes support for the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension.
22

3-
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features such as sorting, filtering and pagination. You just need to focus on defining the resources and implementing your custom business logic. This library has been designed around dependency injection, making extensibility incredibly easy.
3+
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features, such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources. You just need to focus on defining the resources and implementing your custom business logic. This library has been designed around dependency injection, making extensibility incredibly easy.
44

55
For more information, visit [www.jsonapi.net](https://www.jsonapi.net/).

‎README.md

Lines changed: 170 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,198 @@
11
<a href="https://www.jsonapi.net"><img src="docs/home/assets/img/logo.svg" style="height: 345px; width: 345px"/></a>
22

33
# JsonApiDotNetCore
4-
A framework for building [JSON:API](https://jsonapi.org/) compliant REST APIs using .NET Core and Entity Framework Core. Includes support for the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension.
5-
6-
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources. You just need to focus on defining the resources and implementing your custom business logic. This library has been designed around dependency injection, making extensibility incredibly easy.
74

85
[![Build](https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/workflows/build.yml?query=branch%3Amaster)
96
[![Coverage](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore/branch/master/graph/badge.svg?token=pn036tWV8T)](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore)
107
[![NuGet](https://img.shields.io/nuget/v/JsonApiDotNetCore.svg)](https://www.nuget.org/packages/JsonApiDotNetCore/)
8+
[![GitHub License](https://img.shields.io/github/license/json-api-dotnet/JsonApiDotNetCore)](LICENSE)
119
[![Chat](https://badges.gitter.im/json-api-dotnet-core/Lobby.svg)](https://gitter.im/json-api-dotnet-core/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
1210
[![FIRST-TIMERS](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://www.firsttimersonly.com/)
1311

14-
## Getting Started
12+
A framework for building [JSON:API](https://jsonapi.org/) compliant REST APIs using ASP.NET Core and Entity Framework Core. Includes support for the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension.
1513

16-
First, declare your models:
14+
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features, such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources. You just need to focus on defining the resources and implementing your custom business logic. This library has been designed around dependency injection, making extensibility incredibly easy.
1715

18-
```c#
19-
#nullable enable
16+
> [!NOTE]
17+
> OpenAPI support is now [available](https://www.jsonapi.net/usage/openapi.html), currently in preview. Give it a try!
2018
21-
[Resource]
22-
public class Article : Identifiable<Guid>
23-
{
24-
[Attr]
25-
public string Name { get; set; } = null!;
26-
}
27-
```
19+
## Getting started
2820

29-
Then, add the middleware:
21+
The following steps describe how to create a JSON:API project.
3022

31-
```c#
32-
// Program.cs
23+
1. Install the JsonApiDotNetCore package, along with your preferred Entity Framework Core provider:
24+
```bash
25+
dotnet add package JsonApiDotNetCore
26+
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
27+
```
3328

34-
builder.Services.AddJsonApi<AppDbContext>();
29+
1. Declare your entities, annotated with JsonApiDotNetCore attributes:
30+
```c#
31+
#nullable enable
32+
33+
[Resource]
34+
public class Person : Identifiable<long>
35+
{
36+
[Attr] public string? FirstName { get; set; }
37+
[Attr] public string LastName { get; set; } = null!;
38+
[HasMany] public ISet<Person> Children { get; set; } = new HashSet<Person>();
39+
}
40+
```
3541

36-
// ...
42+
1. Define your `DbContext`, seeding the database with sample data:
43+
```c#
44+
public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
45+
{
46+
public DbSet<Person> People => Set<Person>();
47+
48+
protected override void OnConfiguring(DbContextOptionsBuilder builder)
49+
{
50+
builder.UseSqlite("Data Source=SampleDb.db");
51+
builder.UseAsyncSeeding(async (dbContext, _, cancellationToken) =>
52+
{
53+
dbContext.Set<Person>().Add(new Person
54+
{
55+
FirstName = "John",
56+
LastName = "Doe",
57+
Children =
58+
{
59+
new Person
60+
{
61+
FirstName = "Baby",
62+
LastName = "Doe"
63+
}
64+
}
65+
});
66+
await dbContext.SaveChangesAsync(cancellationToken);
67+
});
68+
}
69+
}
70+
```
3771

38-
app.UseRouting();
39-
app.UseJsonApi();
40-
app.MapControllers();
41-
```
72+
1. Configure Entity Framework Core and JsonApiDotNetCore in `Program.cs`:
73+
```c#
74+
var builder = WebApplication.CreateBuilder(args);
75+
builder.Services.AddDbContext<AppDbContext>();
76+
builder.Services.AddJsonApi<AppDbContext>(options =>
77+
{
78+
options.UseRelativeLinks = true;
79+
options.IncludeTotalResourceCount = true;
80+
});
81+
82+
var app = builder.Build();
83+
app.UseRouting();
84+
app.UseJsonApi();
85+
app.MapControllers();
86+
await CreateDatabaseAsync(app.Services);
87+
app.Run();
88+
89+
static async Task CreateDatabaseAsync(IServiceProvider serviceProvider)
90+
{
91+
await using var scope = serviceProvider.CreateAsyncScope();
92+
var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
93+
await dbContext.Database.EnsureDeletedAsync();
94+
await dbContext.Database.EnsureCreatedAsync();
95+
}
96+
```
4297

43-
Finally, you can query your JSON:API server:
98+
1. Start your API
99+
```bash
100+
dotnet run
101+
```
44102

45-
```
46-
$ curl -i http://localhost:5000/authors
47-
48-
HTTP/1.1 200 OK
49-
Content-Type: application/vnd.api+json
50-
ETag: "078F7A2A7D0B3C0B56952AD3E35E5908"
51-
52-
{
53-
"links": {
54-
"self": "http://localhost:5000/authors",
55-
"first": "http://localhost:5000/authors"
56-
},
57-
"data": [
58-
{
59-
"type": "authors",
60-
"id": "8977e0ab-4af8-418b-8859-a3d7a22367d7",
61-
"attributes": { "name": "William Shakespeare" },
62-
"links": { "self": "http://localhost:5000/authors/8977e0ab-4af8-418b-8859-a3d7a22367d7" }
63-
}
64-
]
65-
}
66-
```
103+
1. Send a GET request to retrieve data:
104+
```bash
105+
GET http://localhost:5000/people?filter=equals(firstName,'John')&include=children HTTP/1.1
106+
```
67107

68-
See [our documentation](https://www.jsonapi.net/) for detailed usage. The [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory provides up-to-date sample applications. There is also a [Todo List App](https://github.com/json-api-dotnet/TodoListExample) that includes a JsonApiDotNetCore API and an EmberJs client with token authentication.
108+
```json
109+
{
110+
"links": {
111+
"self": "/people?filter=equals(firstName,%27John%27)&include=children",
112+
"first": "/people?filter=equals(firstName,%27John%27)&include=children",
113+
"last": "/people?filter=equals(firstName,%27John%27)&include=children"
114+
},
115+
"data": [
116+
{
117+
"type": "people",
118+
"id": "1",
119+
"attributes": {
120+
"firstName": "John",
121+
"lastName": "Doe"
122+
},
123+
"relationships": {
124+
"children": {
125+
"links": {
126+
"self": "/people/1/relationships/children",
127+
"related": "/people/1/children"
128+
},
129+
"data": [
130+
{
131+
"type": "people",
132+
"id": "2"
133+
}
134+
]
135+
}
136+
},
137+
"links": {
138+
"self": "/people/1"
139+
}
140+
}
141+
],
142+
"included": [
143+
{
144+
"type": "people",
145+
"id": "2",
146+
"attributes": {
147+
"firstName": "Baby",
148+
"lastName": "Doe"
149+
},
150+
"relationships": {
151+
"children": {
152+
"links": {
153+
"self": "/people/2/relationships/children",
154+
"related": "/people/2/children"
155+
}
156+
}
157+
},
158+
"links": {
159+
"self": "/people/2"
160+
}
161+
}
162+
],
163+
"meta": {
164+
"total": 1
165+
}
166+
}
167+
```
69168

70-
## Learn More
169+
## Learn more
71170

72-
The following links explain what this project is, why it exists, and how you can use it.
171+
The following links explain what this project provides, why it exists, and how you can use it.
73172

74173
### About
75174

76175
- [What is JSON:API and why should I use it?](https://nordicapis.com/the-benefits-of-using-json-api/) (blog, 2017)
77176
- [Pragmatic JSON:API Design](https://www.youtube.com/watch?v=3jBJOga4e2Y) (video, 2017)
78177
- [JSON:API and JsonApiDotNetCore](https://www.youtube.com/watch?v=79Oq0HOxyeI) (video, 2021)
79178
- [JsonApiDotNetCore Release 4.0](https://dev.to/wunki/getting-started-5dkl) (blog, 2020)
80-
- [JSON:API, .Net Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
179+
- [JSON:API, ASP.NET Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
81180
- [Embercasts: Full Stack Ember with ASP.NET Core](https://www.embercasts.com/course/full-stack-ember-with-dotnet/watch/whats-in-this-course-cs) (paid course, 2017)
82181

83-
### Official Documentation
182+
### Official documentation
84183

184+
- [JsonApiDotNetCore documentation](https://www.jsonapi.net/)
85185
- [The JSON:API specification](https://jsonapi.org/format/)
86-
- [JsonApiDotNetCore website](https://www.jsonapi.net/)
87-
- [Roadmap](ROADMAP.md)
186+
- [JsonApiDotNetCore roadmap](ROADMAP.md)
187+
188+
### Samples
88189

89-
### Related Projects
190+
- The [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory provides ready-to-run sample API projects
191+
- Many advanced use cases are covered by integration tests, which can be found [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests).
192+
This includes topics such as batching, multi-tenancy, authorization, soft-deletion, obfuscated IDs, resource inheritance, alternate routing, custom metadata, error handling and logging.
193+
- The [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample) showcases a JsonApiDotNetCore API and an Ember.js client with token authentication.
194+
195+
### Related projects
90196

91197
- [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb)
92198
- [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample)
@@ -113,10 +219,6 @@ See also our [versioning policy](./VERSIONING_POLICY.md).
113219
| master | Preview | 8 | 8, 9 |
114220
| | | 9 | 9 |
115221

116-
## Contributing
117-
118-
Have a question, found a bug or want to submit code changes? See our [contributing guidelines](./.github/CONTRIBUTING.md).
119-
120222
## Trying out the latest build
121223

122224
After each commit to the master branch, a new pre-release NuGet package is automatically published to [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry).
@@ -138,15 +240,19 @@ To try it out, follow the steps below:
138240
and retry with the `--store-password-in-clear-text` switch added.
139241
1. Restart your IDE, open your project, and browse the list of packages from the github-json-api feed (make sure pre-release packages are included).
140242

141-
## Development
243+
## Contributing
244+
245+
Have a question, found a bug or want to submit code changes? See our [contributing guidelines](./.github/CONTRIBUTING.md).
246+
247+
## Build from source
142248

143249
To build the code from this repository locally, run:
144250

145251
```bash
146252
dotnet build
147253
```
148254

149-
Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can be propped up via:
255+
Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can started via:
150256

151257
```bash
152258
pwsh run-docker-postgres.ps1
@@ -166,5 +272,9 @@ pwsh Build.ps1
166272

167273
## Sponsors
168274

275+
We are very grateful to the sponsors below, who have provided us with a no-cost license for their tools.
276+
169277
<a href="https://jb.gg/OpenSourceSupport"><img align="middle" src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg" alt="JetBrains Logo" style="width:150px"></a> &nbsp;
170278
<a href="https://www.araxis.com/buy/open-source"><img align="middle" src="https://www.araxis.com/theme/37/img/araxis-logo-lg.svg" alt="Araxis Logo" style="width:150px"></a>
279+
280+
Do you like this project? Consider to [sponsor](https://github.com/sponsors/json-api-dotnet), or just reward us by giving our repository a star.

‎docs/home/index.html

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@
44
<meta charset="utf-8">
55
<meta content="width=device-width, initial-scale=1.0" name="viewport">
66
<title>JsonApiDotNetCore documentation</title>
7-
<meta content="A framework for building JSON:API compliant REST APIs using .NET Core and Entity Framework Core. Includes support for Atomic Operations." name="description">
7+
<meta content="A framework for building JSON:API compliant REST APIs using ASP.NET Core and Entity Framework Core. Includes support for the Atomic Operations extension." name="description">
88
<meta content="jsonapidotnetcore jsonapi json:api dotnet asp.net" name="keywords">
99
<link href="favicon.ico" rel="icon">
1010
<link href="favicon.ico" rel="apple-touch-icon">
1111
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,600,600i,700,700i|Raleway:300,300i,400,400i,600,600i,700,700i" rel="stylesheet">
1212
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.5.0/css/bootstrap.min.css" rel="stylesheet">
1313
<link href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-icons/1.11.3/font/bootstrap-icons.min.css" rel="stylesheet">
1414
<link href="https://unpkg.com/boxicons@2.0.7/css/boxicons.min.css" rel="stylesheet">
15-
<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.4.0/styles/default.min.css" rel="stylesheet">
15+
<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css" rel="stylesheet">
1616
<link href="https://cdnjs.cloudflare.com/ajax/libs/aos/2.3.4/aos.css" rel="stylesheet">
1717
<link href="styles/home.css" rel="stylesheet">
1818
<link href="styles/icofont.min.css" rel="stylesheet">
@@ -51,8 +51,8 @@
5151
<div class="col-lg-7 pt-5 pt-lg-0 order-2 order-lg-1">
5252
<h1>JsonApiDotNetCore</h1>
5353
<h2>
54-
A framework for building <a href="https://jsonapi.org/" target="_blank">JSON:API</a> compliant REST APIs using .NET Core and Entity Framework Core.
55-
Includes support for <a href="https://jsonapi.org/ext/atomic/" target="_blank">Atomic Operations</a>.
54+
A framework for building <a href="https://jsonapi.org/" target="_blank">JSON:API</a> compliant REST APIs using ASP.NET Core and Entity Framework Core.
55+
Includes support for the <a href="https://jsonapi.org/ext/atomic/" target="_blank">Atomic Operations</a> extension.
5656
</h2>
5757
<a href="#about" class="btn-get-started scrollto">Read more</a>
5858
<a href="../../getting-started/install.html" class="btn-get-started">Getting started</a>
@@ -82,7 +82,9 @@ <h3 data-aos="fade-up">Objectives</h3>
8282
<div class="col-md-6" data-aos="fade-up" data-aos-delay="100">
8383
<i class="bx bxs-package"></i>
8484
<h4>Eliminate boilerplate</h4>
85-
<p>We strive to eliminate as much boilerplate as possible by offering out-of-the-box features such as sorting, filtering and pagination.</p>
85+
<p>
86+
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features, such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources.
87+
</p>
8688
</div>
8789
<div class="col-md-6" data-aos="fade-up" data-aos-delay="200">
8890
<i class="bx bx-category-alt"></i>
@@ -112,7 +114,7 @@ <h4 class="title">Filtering</h4>
112114
<div class="icon-box">
113115
<div class="icon"><i class="bx bx-sort-a-z"></i></div>
114116
<h4 class="title">Sorting</h4>
115-
<p class="description">Order resources on one or multiple attributes using the <code>sort</code> query string parameter</p>
117+
<p class="description">Order resources on multiple attributes using the <code>sort</code> query string parameter</p>
116118
</div>
117119
</div>
118120
<div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="300" id="pagination">
@@ -174,7 +176,7 @@ <h2>Example usage</h2>
174176
<div class="icon"><i class="bx bx-detail"></i></div>
175177
<h4 class="title">Resource</h4>
176178
<pre>
177-
<code>#nullable enable
179+
<code class="language-csharp">#nullable enable
178180

179181
public class Article : Identifiable&lt;long&gt;
180182
{
@@ -213,7 +215,7 @@ <h4 class="title">Resource</h4>
213215
<div class="icon-box code-example">
214216
<div class="icon"><i class="bx bx-message-rounded-detail"></i></div>
215217
<h4 class="title">Request</h4>
216-
<pre><code>GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields[articles]=title,summary&include=author HTTP/1.1</code></pre>
218+
<pre><code class="language-http">GET /articles?filter=contains(summary,'web')&amp;sort=-lastModifiedAt&amp;fields[articles]=title,summary&amp;include=author HTTP/1.1</code></pre>
217219
</div>
218220
</div>
219221
</div>
@@ -223,14 +225,14 @@ <h4 class="title">Request</h4>
223225
<div class="icon"><i class="bx bx-message-rounded-detail bx-flip-horizontal"></i></div>
224226
<h4 class="title">Response</h4>
225227
<pre>
226-
<code>{
228+
<code class="language-json">{
227229
"meta": {
228230
"totalResources": 1
229231
},
230232
"links": {
231-
"self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
232-
"first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
233-
"last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author"
233+
"self": "/articles?filter=contains(summary,'web')&amp;sort=-lastModifiedAt&amp;fields%5Barticles%5D=title,summary&amp;include=author",
234+
"first": "/articles?filter=contains(summary,'web')&amp;sort=-lastModifiedAt&amp;fields%5Barticles%5D=title,summary&amp;include=author",
235+
"last": "/articles?filter=contains(summary,'web')&amp;sort=-lastModifiedAt&amp;fields%5Barticles%5D=title,summary&amp;include=author"
234236
},
235237
"data": [
236238
{

0 commit comments

Comments
 (0)