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

ERNI Academy Hateoas Api boilerplate to start a Hateoas Api.

Built With

This boilerplate is using the following technologies:

• Net 6.0

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:

.

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

Installation

Installation instructions Erni Api Hateoas by running:

1. Clone the repo

   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

builder.Services.AddControllers().AddHateoas();

In case you have a multiprojects solution and you have the required files out of the main project then:

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:

.

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

.

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

.

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:

.

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

Then responses would look like:

• For Json

.

• For Xml

.

Contributing

Please see our Contribution Guide to learn how to contribute.

License

(LICENSE) © 2022 ERNI - Swiss Software Engineering

Code of conduct

Please see our Code of Conduct

Stats

Follow us

Contact

📧 esp-services@betterask.erni

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Robertcs8 💻 🖋 📖 🎨 🤔 🚧 ⚠️ 💡 👀

Rabosa616 💻 🖋 📖 🎨 🤔 🚧 ⚠️ 💡 👀

This project follows the all-contributors specification. Contributions of any kind welcome!