Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize README #1584

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Reorganize README #1584

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bdfc9c
Reorganize README (fix #1567)
verdie-g Jun 30, 2024
f059fcd
Update README.md
verdie-g Jul 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 56 additions & 37 deletions README.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Current structure:

## Contributing
## Trying out the latest build
## Development

I'd like to change that to:

## Daily builds (was: Trying out the latest build)
## Contributing
### Build from source (was: Development)

This better matches the level of involvement going down.

Original file line number Diff line number Diff line change
@@ -1,52 +1,23 @@
<a href="https://www.jsonapi.net"><img src="docs/home/assets/img/logo.svg" style="height: 345px; width: 345px"/></a>
<p align="center">
<a href="https://www.jsonapi.net"><img src="docs/home/assets/img/logo.svg" style="height: 345px; width: 345px"/></a>
</p>

Comment on lines +1 to +3
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert this change. I recently removed the centering due to issues on mobile devices.

# JsonApiDotNetCore
A framework for building [JSON:API](http://jsonapi.org/) compliant REST APIs using .NET Core and Entity Framework Core. Includes support for [Atomic Operations](https://jsonapi.org/ext/atomic/).
A framework for building [JSON:API](http://jsonapi.org/) compliant REST APIs using .NET Core and Entity Framework Core. Includes support for the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added "the ... extension" here to help the reader understand what we are talking about.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good one. Can you replicate this change to the following files?

  • /PackageReadme.md
  • /docs/home/index.html
  • .../JsonApiDotNetCore.csproj

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.

bkoelman marked this conversation as resolved.
Show resolved Hide resolved
verdie-g marked this conversation as resolved.
Show resolved Hide resolved
[![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)
[![Coverage](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore/branch/master/graph/badge.svg?token=pn036tWV8T)](https://codecov.io/gh/json-api-dotnet/JsonApiDotNetCore)
[![NuGet](https://img.shields.io/nuget/v/JsonApiDotNetCore.svg)](https://www.nuget.org/packages/JsonApiDotNetCore/)
[![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)
[![FIRST-TIMERS](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](http://www.firsttimersonly.com/)

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.

## Getting Started

These are some steps you can take to help you understand what this project is and how you can use it:

### About
- [What is JSON:API and why should I use it?](https://nordicapis.com/the-benefits-of-using-json-api/) (blog, 2017)
- [Pragmatic JSON:API Design](https://www.youtube.com/watch?v=3jBJOga4e2Y) (video, 2017)
- [JSON:API and JsonApiDotNetCore](https://www.youtube.com/watch?v=79Oq0HOxyeI) (video, 2021)
- [JsonApiDotNetCore Release 4.0](https://dev.to/wunki/getting-started-5dkl) (blog, 2020)
- [JSON:API, .Net Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
- [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)

### Official documentation
- [The JSON:API specification](https://jsonapi.org/format/)
- [JsonApiDotNetCore website](https://www.jsonapi.net/)
- [Roadmap](ROADMAP.md)

## Related Projects

- [Performance Reports](https://github.com/json-api-dotnet/PerformanceReports)
- [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb)
- [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample)

## Examples

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.

## Installation and Usage

See [our documentation](https://www.jsonapi.net/) for detailed usage.

### Models
First declare you models

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what to exactly provide here. It lacks basic steps such as: create project, install packages, define DbContext, seed the db, start the server, etc. So this isn't a Getting Started with literal steps to follow, but merely a feature showcase.

The current sample is inconsistent, in that it uses int for ID, but the JSON:API snippet contains GUIDs. We may want to adapt to the sample here: provide the steps to produce that output. Or perhaps a simplified form to save screen space. What do you think?

```c#
#nullable enable

[Resource]
public class Article : Identifiable<int>
{
Expand All @@ -55,7 +26,7 @@ public class Article : Identifiable<int>
}
```

### Middleware
then add the middlewares

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plural form of middleware is middleware, see https://english.stackexchange.com/questions/257120/middleware-vs-middlewares.

```c#
// Program.cs
Expand All @@ -69,6 +40,54 @@ app.UseJsonApi();
app.MapControllers();
```

finally you can query your JSON:API

```
$ curl -i http://localhost:18574/authors

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
ETag: "078F7A2A7D0B3C0B56952AD3E35E5908"

{
"links": {
"self": "http://localhost:18574/authors",
"first": "http://localhost:18574/authors"
},
"data": [
{
"type": "authors",
"id": "8977e0ab-4af8-418b-8859-a3d7a22367d7",
"attributes": { "name": "William Shakespeare" },
"links": { "self": "http://localhost:18574/authors/8977e0ab-4af8-418b-8859-a3d7a22367d7" }
}
]
}
```

See [our documentation](https://www.jsonapi.net/) for detailed usage and the [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory for up-to-date sample applications.

Copy link
Contributor Author

@verdie-g verdie-g Jun 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the comment about the EmberJS example because I don't think that example is more relevant than others.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's especially relevant because EmberJS is where JSON:API was born. We attract EmberJS developers looking for "the .NET way" to use JSON:API. This example shows that JADNC is compatible with EmberJS, by providing a fully-working end-to-end example, which includes authentication between EmberJS and .NET. If we had a fully working end-to-end Blazor sample, I'd mention it separately as well.

## Resources

Copy link
Contributor Author

@verdie-g verdie-g Jun 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it can simply be renamed to "Resources".

That's an overloaded term we should avoid here.

Links? Learning Resources? Learn More?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like "Learn More"

### About
- [What is JSON:API and why should I use it?](https://nordicapis.com/the-benefits-of-using-json-api/) (blog, 2017)
- [Pragmatic JSON:API Design](https://www.youtube.com/watch?v=3jBJOga4e2Y) (video, 2017)
- [JSON:API and JsonApiDotNetCore](https://www.youtube.com/watch?v=79Oq0HOxyeI) (video, 2021)
- [JsonApiDotNetCore Release 4.0](https://dev.to/wunki/getting-started-5dkl) (blog, 2020)
- [JSON:API, .Net Core, EmberJS](https://youtu.be/KAMuo6K7VcE) (video, 2017)
- [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)

### Official documentation
- [The JSON:API specification](https://jsonapi.org/format/)
- [JsonApiDotNetCore website](https://www.jsonapi.net/)
- [Roadmap](ROADMAP.md)

### Related Projects

- [Performance Reports](https://github.com/json-api-dotnet/PerformanceReports)
- [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb)
- [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample)

## Compatibility

The following chart should help you pick the best version, based on your environment.
Expand Down
Loading