Skip to content

Commit 4da3f25

Browse files
bkoelmanverdie-g
bkoelman
and
verdie-g
authored
Reorganize README, documentation updates (#1718)
* Reorganize README (fix #1567) * Update README.md Co-authored-by: Bart Koelman <[email protected]> * Documentation updates * Reverse version table and update * Use collapsed section for JSON response --------- Co-authored-by: Grégoire <[email protected]>
1 parent c76ecdb commit 4da3f25

File tree

8 files changed

+221
-78
lines changed

8 files changed

+221
-78
lines changed

‎LICENSE

+1
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

+2-2
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

+200-60
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,207 @@
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 [Atomic Operations](https://jsonapi.org/ext/atomic/).
54

65
[![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)
76
[![Coverage](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore/branch/master/graph/badge.svg?token=pn036tWV8T)](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore)
87
[![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)
99
[![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)
1010
[![FIRST-TIMERS](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://www.firsttimersonly.com/)
1111

12-
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.
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.
1313

14-
## Getting Started
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.
1515

16-
These are some steps you can take to help you understand what this project is and how you can use it:
16+
> [!NOTE]
17+
> OpenAPI support is now [available](https://www.jsonapi.net/usage/openapi.html), currently in preview. Give it a try!
1718
18-
### About
19-
- [What is JSON:API and why should I use it?](https://nordicapis.com/the-benefits-of-using-json-api/) (blog, 2017)
20-
- [Pragmatic JSON:API Design](https://www.youtube.com/watch?v=3jBJOga4e2Y) (video, 2017)
21-
- [JSON:API and JsonApiDotNetCore](https://www.youtube.com/watch?v=79Oq0HOxyeI) (video, 2021)
22-
- [JsonApiDotNetCore Release 4.0](https://dev.to/wunki/getting-started-5dkl) (blog, 2020)
23-
- [JSON:API, .Net Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
24-
- [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)
19+
## Getting started
2520

26-
### Official documentation
27-
- [The JSON:API specification](https://jsonapi.org/format/)
28-
- [JsonApiDotNetCore website](https://www.jsonapi.net/)
29-
- [Roadmap](ROADMAP.md)
21+
The following steps describe how to create a JSON:API project.
3022

31-
## Related Projects
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+
```
3228

33-
- [Performance Reports](https://github.com/json-api-dotnet/PerformanceReports)
34-
- [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb)
35-
- [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample)
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+
```
3641

37-
## Examples
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+
```
3871

39-
See the [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory for 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.
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+
```
4097

41-
## Installation and Usage
98+
1. Start your API
99+
```bash
100+
dotnet run
101+
```
42102

43-
See [our documentation](https://www.jsonapi.net/) for detailed usage.
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+
```
44107

45-
### Models
108+
<details>
109+
<summary>Expand to view the JSON response</summary>
110+
111+
```json
112+
{
113+
"links": {
114+
"self": "/people?filter=equals(firstName,%27John%27)&include=children",
115+
"first": "/people?filter=equals(firstName,%27John%27)&include=children",
116+
"last": "/people?filter=equals(firstName,%27John%27)&include=children"
117+
},
118+
"data": [
119+
{
120+
"type": "people",
121+
"id": "1",
122+
"attributes": {
123+
"firstName": "John",
124+
"lastName": "Doe"
125+
},
126+
"relationships": {
127+
"children": {
128+
"links": {
129+
"self": "/people/1/relationships/children",
130+
"related": "/people/1/children"
131+
},
132+
"data": [
133+
{
134+
"type": "people",
135+
"id": "2"
136+
}
137+
]
138+
}
139+
},
140+
"links": {
141+
"self": "/people/1"
142+
}
143+
}
144+
],
145+
"included": [
146+
{
147+
"type": "people",
148+
"id": "2",
149+
"attributes": {
150+
"firstName": "Baby",
151+
"lastName": "Doe"
152+
},
153+
"relationships": {
154+
"children": {
155+
"links": {
156+
"self": "/people/2/relationships/children",
157+
"related": "/people/2/children"
158+
}
159+
}
160+
},
161+
"links": {
162+
"self": "/people/2"
163+
}
164+
}
165+
],
166+
"meta": {
167+
"total": 1
168+
}
169+
}
170+
```
46171

47-
```c#
48-
#nullable enable
172+
</details>
49173

50-
[Resource]
51-
public class Article : Identifiable<int>
52-
{
53-
[Attr]
54-
public string Name { get; set; } = null!;
55-
}
56-
```
174+
## Learn more
57175

58-
### Middleware
176+
The following links explain what this project provides, why it exists, and how you can use it.
59177

60-
```c#
61-
// Program.cs
178+
### About
62179

63-
builder.Services.AddJsonApi<AppDbContext>();
180+
- [What is JSON:API and why should I use it?](https://nordicapis.com/the-benefits-of-using-json-api/) (blog, 2017)
181+
- [Pragmatic JSON:API Design](https://www.youtube.com/watch?v=3jBJOga4e2Y) (video, 2017)
182+
- [JSON:API and JsonApiDotNetCore](https://www.youtube.com/watch?v=79Oq0HOxyeI) (video, 2021)
183+
- [JsonApiDotNetCore Release 4.0](https://dev.to/wunki/getting-started-5dkl) (blog, 2020)
184+
- [JSON:API, ASP.NET Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
185+
- [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)
64186

65-
// ...
187+
### Official documentation
66188

67-
app.UseRouting();
68-
app.UseJsonApi();
69-
app.MapControllers();
70-
```
189+
- [JsonApiDotNetCore documentation](https://www.jsonapi.net/)
190+
- [The JSON:API specification](https://jsonapi.org/format/)
191+
- [JsonApiDotNetCore roadmap](ROADMAP.md)
192+
193+
### Samples
194+
195+
- The [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory provides ready-to-run sample API projects
196+
- 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).
197+
This includes topics such as batching, multi-tenancy, authorization, soft-deletion, obfuscated IDs, resource inheritance, alternate routing, custom metadata, error handling and logging.
198+
- 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.
199+
200+
### Related projects
201+
202+
- [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb)
203+
- [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample)
204+
- [Performance Reports](https://github.com/json-api-dotnet/PerformanceReports)
71205

72206
## Compatibility
73207

@@ -76,23 +210,21 @@ See also our [versioning policy](./VERSIONING_POLICY.md).
76210

77211
| JsonApiDotNetCore | Status | .NET | Entity Framework Core |
78212
| ----------------- | ------------ | -------- | --------------------- |
79-
| 3.x | Stable | Core 2.x | 2.x |
80-
| 4.x | Stable | Core 3.1 | 3.1, 5 |
81-
| | | 5 | 5 |
82-
| | | 6 | 5 |
83-
| 5.0.0-5.0.2 | Stable | 6 | 6 |
84-
| 5.0.3-5.4.0 | Stable | 6 | 6, 7 |
85-
| | | 7 | 7 |
86-
| 5.5+ | Stable | 6 | 6, 7 |
87-
| | | 7 | 7 |
213+
| master | Preview | 9 | 9 |
88214
| | | 8 | 8, 9 |
89-
| | | 9 | 9 |
90-
| master | Preview | 8 | 8, 9 |
91-
| | | 9 | 9 |
92-
93-
## Contributing
94-
95-
Have a question, found a bug or want to submit code changes? See our [contributing guidelines](./.github/CONTRIBUTING.md).
215+
| 5.7.0+ | Stable | 9 | 9 |
216+
| | | 8 | 8, 9 |
217+
| 5.5.0-5.6.0 | Stable | 9 | 9 |
218+
| | | 8 | 8, 9 |
219+
| | | 7 | 7 |
220+
| | | 6 | 6, 7 |
221+
| 5.0.3-5.4.0 | Stable | 7 | 7 |
222+
| | | 6 | 6, 7 |
223+
| 5.0.0-5.0.2 | Stable | 6 | 6 |
224+
| 4.x | Stable | 6 | 5 |
225+
| | | 5 | 5 |
226+
| | | Core 3.1 | 3.1, 5 |
227+
| 3.x | Stable | Core 2.x | 2.x |
96228

97229
## Trying out the latest build
98230

@@ -115,15 +247,19 @@ To try it out, follow the steps below:
115247
and retry with the `--store-password-in-clear-text` switch added.
116248
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).
117249

118-
## Development
250+
## Contributing
251+
252+
Have a question, found a bug or want to submit code changes? See our [contributing guidelines](./.github/CONTRIBUTING.md).
253+
254+
## Build from source
119255

120256
To build the code from this repository locally, run:
121257

122258
```bash
123259
dotnet build
124260
```
125261

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

128264
```bash
129265
pwsh run-docker-postgres.ps1
@@ -143,5 +279,9 @@ pwsh Build.ps1
143279

144280
## Sponsors
145281

282+
We are very grateful to the sponsors below, who have provided us with a no-cost license for their tools.
283+
146284
<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;
147285
<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>
286+
287+
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.

0 commit comments

Comments
 (0)