Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ERNI-Academy/asset-restfullapi-hateoas

This project implements a Restfull Hateoas Api
https://github.com/ERNI-Academy/asset-restfullapi-hateoas

docker dotnet hateoas net6 restfull-api

Last synced: 3 months ago
JSON representation

This project implements a Restfull Hateoas Api

Host: GitHub
URL: https://github.com/ERNI-Academy/asset-restfullapi-hateoas
Owner: ERNI-Academy
License: mit
Created: 2022-05-20T09:27:30.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2023-06-27T23:12:05.000Z (over 1 year ago)
Last Synced: 2024-05-12T06:34:25.913Z (6 months ago)
Topics: docker, dotnet, hateoas, net6, restfull-api
Language: C#
Homepage: https://erni-academy.github.io/asset-restfullapi-hateoas/
Size: 383 KB
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Authors: AUTHORS.md

Awesome Lists containing this project

awesome-resources - asset-restfullapi-hateoas

README

# About ERNI Api Hypertext as the Engine of Application State (Hateoas)

ERNI Academy Hateoas Api boilerplate to start a Hateoas Api.

[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors)

[![sonarcloud](https://github.com/ERNI-Academy/asset-restfullapi-hateoas/actions/workflows/sonarcloud.yml/badge.svg?branch=main)](https://github.com/ERNI-Academy/asset-restfullapi-hateoas/actions/workflows/sonarcloud.yml)
[![pages-build-deployment](https://github.com/ERNI-Academy/asset-restfullapi-hateoas/actions/workflows/pages/pages-build-deployment/badge.svg?branch=main)](https://github.com/ERNI-Academy/asset-restfullapi-hateoas/actions/workflows/pages/pages-build-deployment)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ERNI-Academy_asset-restfullapi-hateoas&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ERNI-Academy_asset-restfullapi-hateoas)
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=ERNI-Academy_asset-restfullapi-hateoas&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=ERNI-Academy_asset-restfullapi-hateoas)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ERNI-Academy_asset-restfullapi-hateoas&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ERNI-Academy_asset-restfullapi-hateoas)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ERNI-Academy_asset-restfullapi-hateoas&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ERNI-Academy_asset-restfullapi-hateoas)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ERNI-Academy_asset-restfullapi-hateoas&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=ERNI-Academy_asset-restfullapi-hateoas)

## Built With

This boilerplate is using the following technologies:

- [Net 6.0](https://docs.microsoft.com/en-us/dotnet/core/whats-new/dotnet-6)

## Getting Started

When we implement REST APIs, there are 4 levels of maturity to go from API till Fully Restful API:

- **Level 0: The Swamp of POX**: API designed at this level are not at all Rest APIs and this is where SOAP based web services takes place.

- **Level 1: Resource Based Address/Uri**: In this Level, the Concept of Resource-based Address is introduced, which tells you there should be Individual URI for each Resource on the server. It's like reducing the burden from the single endpoint (LEVEL 0 end Point which handles all operations) into multiple Resource Based URIs like Divide and Conquer algorithm.

- **Level 2: Utilize Potential of HTTP**: REST developed under this level leverages the full potential of HTTP as an application Layer Protocol. REST API developed at this LEVEL uses Standard HTTP methods/verbs and different HTTP status codes to do different operations on Resource URI. So, the Request Body will no longer carry Operation information at this level. Hence, this API is much more mature than the API developed at LEVEL 0 and LEVEL 1.

- **Level 3> Use Hypermedia (OR HATEOAS)**: This level makes use of Hypermedia (also Called HATEOAS--Hypermedia as Engine of Application state in REST world), which drives the interaction for the API Client.

Typically, when we perform a REST request, we only get the data and not any actions around it. This is where HATEOAS comes in to fill the gap. A HATEOAS request allows you to not only send the data but also specify the related actions. For example:

![Json request](./docs/images/JsonResponse.PNG "Json request").

As it can be appreciated, it contains the **Links** property which represents all the resources available.

This boilerplate will help you to fullfill level 3 REST Api, so your API will be considered a RestFull API.

## Prerequisites

To run and play with the boilerplates you need to install the following ide:

* Visual Studio 2022

It also uses Docker to deploy the Sample Api:

* [Docker](https://docs.docker.com/desktop/windows/install/)

## Installation

Installation instructions Erni Api Hateoas by running:

1. Clone the repo

```sh
https://github.com/ERNI-Academy/asset-restfullapi-hateoas.git
```

2. Start docker

3. Restore packages

4. Build the application

## Project Structure

### The project contains the following projects

* **Erni.Api.Hateoas.Sample**: this project contains a Sample Api that uses the Core functionality.
* **Erni.Api.Hateoas.**: this project contains the main functionalities to get a functional Hateoas Api.

### The folder structure

. \
├── **Erni.Mobile.Hateoas** \
├── 📁 Dto: Contains all data transfer objects \
│ └── 📄 Link.cs: Base class for Links generations. \
│ └── 📄 LinkCollectionWrapper.cs: Wrapper class for Links. \
│ └── 📄 LinkResourceBase.cs: Base class for LinkCollectionWrapper. \
│ └── 📄 PagedList.cs: Base class to implement the paged list functionality. \
│ └── 📄 PaginationFilter.cs: Class for filtering results. \
│ └── 📄 QueryStringParameters.cs: Class for query string parameters. \
│ └── 📄 ResponseDto.cs: Dynamic class to generate the Api responses. \
├── 📂 Extensions: Contains all custom extension \
│ └── 📄 ServicesExtension.cs: Class that manages dependency injection. \
├── 📂 Formatter: Contains all custom formatters \
│ ├── 📄 JsonHateoasFormatter.cs: Class responsible to customize the json output format when Hateoas needs to be implemented. \
│ ├── 📄 XmlHateoasFormatter.cs: Class responsible to customize the xml output format when Hateoas needs to be implemented. \
├── 📂 Services: Contains all services that the application uses \
│ └── 📄 DataShaper.cs: Shapes the data to fullfill the query filters. \
│ └── 📄 IDataShaper.cs: Interface for DataShaper class. \
│ └── 📄 ILinkGenerator.cs: Interface to be implemented for the Links generators. \
│ └── 📄 ISortHelper.cs: Interface for SortHelper. \
│ └── 📄 SortHelper.cs: Sorts the data to fullfill the query filters.

## How to use it

1. Create your own API project.

2. Add reference to ERNI.Api.Hateoas project.

3. Call the AddHateoas extension method to register all the required services and formatters on your Program.cs.

This will get all required files from your project

```csharp
builder.Services.AddControllers().AddHateoas();
```
In case you have a multiprojects solution and you have the required files out of the main project then:
```csharp
var assemblies = new[]
{
Assembley1,
Assembley2
...
};
builder.Services.AddControllers().AddHateoas(assemblies);
```

4. Implement the ILinkGenerator<> interface for all the Dtos that must implement the Links functionality in their responses. See the example attached:

![Link generator request](./docs/images/LinkGenerator.PNG "Link generator sample").

5. Implement the classes inheriting from QueryStringParameters needed for your endpoints and dtos logic. See the example attached:

![Sample query parameters](./docs/images/SampleQueryParameters.PNG "Query parameters sample class").

6. Your controllers endpoints need to receive the this QueryParameters class as they are going to be used automatically on the Formatters.

![Controller sample](./docs/images/ControllerSample.PNG "Controller sample").

7. Formatters will intercept and format the Responses automatically when a request is performed with the Header **Accept** - **application/json+hateoas** or **Accept** - **application/xml+hateoas**.

Once your sample app is up and running, an Api is listening on the configured port.
Then, a query can be perfomed. Let's see the following example:

![Sample request](./docs/images/SampleRequest.PNG "Sample request").

The Header **Accept** - **application/json+hateoas** could be also **Accept** - **application/xml+hateoas**.

Then responses would look like:

* For Json

![Json request](./docs/images/JsonResponse.PNG "Json request").

* For Xml

![Xml request](./docs/images/XmlResponse.PNG "Xml request").

## Contributing

Please see our [Contribution Guide](CONTRIBUTING.md) to learn how to contribute.

## License

![MIT](https://img.shields.io/badge/License-MIT-blue.svg)

## Code of conduct

Please see our [Code of Conduct](CODE_OF_CONDUCT.md)

## Stats

![https://repobeats.axiom.co/api/embed/92f526f5dc3727059d6341530422d52c504def4d.svg](https://repobeats.axiom.co/api/embed/92f526f5dc3727059d6341530422d52c504def4d.svg)

## Follow us

[![Twitter Follow](https://img.shields.io/twitter/follow/ERNI?style=social)](https://www.twitter.com/ERNI)
[![Twitch Status](https://img.shields.io/twitch/status/erni_academy?label=Twitch%20Erni%20Academy&style=social)](https://www.twitch.tv/erni_academy)
[![YouTube Channel Views](https://img.shields.io/youtube/channel/views/UCkdDcxjml85-Ydn7Dc577WQ?label=Youtube%20Erni%20Academy&style=social)](https://www.youtube.com/channel/UCkdDcxjml85-Ydn7Dc577WQ)
[![Linkedin](https://img.shields.io/badge/linkedin-31k-green?style=social&logo=Linkedin)](https://www.linkedin.com/company/erni)

## Contact

📧 [[email protected]](mailto:[email protected])

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_Robertcs8
💻 🖋 📖 🎨 🤔 🚧 ⚠️ 💡 👀

_Rabosa616
💻 🖋 📖 🎨 🤔 🚧 ⚠️ 💡 👀

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!