RESTworld.Common 1.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package RESTworld.Common --version 1.0.0                
NuGet\Install-Package RESTworld.Common -Version 1.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="RESTworld.Common" Version="1.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add RESTworld.Common --version 1.0.0                
#r "nuget: RESTworld.Common, 1.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install RESTworld.Common as a Cake Addin
#addin nuget:?package=RESTworld.Common&version=1.0.0

// Install RESTworld.Common as a Cake Tool
#tool nuget:?package=RESTworld.Common&version=1.0.0                

RESTworld

RESTworld is a framework which utilizes other common frameworks and patterns alltogether to enable easy and fast creation of a truly RESTful API.

Used frameworks and patterns

  • Entity Framework Core for data access
  • ASP.Net Core for hosting
  • HAL for providing hyperlinks between resources
  • OData for query support on list endpoints
  • AutoMapper for mapping between Entities and DTOs

Pipeline

The most basic pipeline has the following data flow for a request on a list endpoint:

  1. Request
  2. Controller selection through ASP.Net Core
  3. Query parsing through OData
  4. Controller method calls business service method
  5. Service gets the data through Entity Framework Core
  6. Entity Framework Core translates the query into SQL and gets the data from the database
  7. Business service translates Entities into DTOs through Automapper
  8. Controller wraps the result in a HAL response
  9. Result

Usage

Solution structure

If your API gets the name MyApi, structure your Solution with the following Projects:

  • MyApi (ASP.Net Core Web API)
    • References RESTworld.AspNetCore, MyApi.Business
    • Contains your startup logic and your custom controllers
  • MyApi.Business
    • References RESTworld.Business, MyApi.Data
    • Contains your AutoMapperConfiguration and your custom services
  • MyApi.Data
    • References RESTworld.EntityFrameworkCore, MyApi.Common
    • Contains your Entity Framework Core Database Model including Entities and Migrations
  • MyApi.Common
    • References RESTworld.Common
    • Contains your DTOs and Enums

Startup configuration

Add the following to your appsettings.json

"RESTworld": {
  "MaxNumberForListEndpoint": <whatever is an appropriate number of resources for one page>
}

Change your Program.cs to the following

namespace MyApi
{
    public class Program
    {
        public static void Main(string[] args)
        {
            RESTworld.AspNetCore.Program<Startup>.Main(args);
        }
    }
}

Change or add your Startup class

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using RESTworld.Business.Abstractions;
using MyApi.Common.Dtos;
using MyApi.Data;
using MyApi.Data.Models;
using MyApi.Business;

namespace MyApi
{
    public class Startup : RESTworld.AspNetCore.StartupBase
    {
        public Startup(IConfiguration configuration)
            : base(configuration)
        {
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public override void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            base.Configure(app, env);

            // Optionally migrate your database to the latest version during startup
            MigrateDatabase<TDbContext>(app);
        }

        // This method gets called by the runtime. Use this method to add services to the container.
        public override void ConfigureServices(IServiceCollection services)
        {
            // Database
            services.AddDbContextFactoryWithDefaults<MyDatabase>(Configuration);
            services.AddODataModelForDbContext<MyDatabase>();
            
            // Default pipeline
            services.AddRestPipeline<TContext, TEntity, TCreateDto, TGetListDto, TGetFullDto, TUpdateDto>();

            // With custom service
            services.AddRestPipelineWithCustomService<TContext, TEntity, TCreateDto, TGetListDto, TGetFullDto, TUpdateDto, TService>();

            // With custom controller
            services.AddRestPipelineWithCustomController<TContext, TEntity, TCreateDto, TGetListDto, TGetFullDto, TUpdateDto, TController>();

            base.ConfigureServices(services);
        }

        protected override void ConfigureAutomapper(IMapperConfigurationExpression config)
            => new AutoMapperConfiguration().ConfigureAutomapper(config);
    }
}

Add an AutoMapperConfiguration to your MyApi.Business project

using AutoMapper;
using MyApi.Common.Dtos;
using MyApi.Common.Enums;
using MyApi.Data.Models;

namespace MyApi.Business
{
    public class AutoMapperConfiguration
    {
        public void ConfigureAutomapper(IMapperConfigurationExpression config)
        {
            config.CreateMap<TEntity, TDto>();

            // Add more mappings
        }
    }
}

That's it. Now you can start your API and use a HAL browser like https://chatty42.herokuapp.com/hal-explorer/index.html#uri=https://localhost:5001 to browse your API. If you are using a launchSettings.json, I suggest to use this as your "launchUrl".

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net5.0

    • No dependencies.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on RESTworld.Common:

Package Downloads
RESTworld.EntityFrameworkCore

Package Description

RESTworld.Client.Net

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
10.0.0 115 11/20/2024
9.1.1 519 10/11/2024
9.1.0 225 9/27/2024
9.0.0 573 7/3/2024
8.0.0 226 6/4/2024
7.2.0 833 1/9/2024
7.1.0 228 12/22/2023
7.0.0 799 11/15/2023
6.1.0 367 10/23/2023
6.0.0 395 9/27/2023
5.3.0 784 7/3/2023
5.2.2 1,139 6/14/2023
5.2.1 481 5/25/2023
5.2.0 560 4/30/2023
5.1.2 523 3/12/2023
5.1.1 727 2/22/2023
5.1.0 419 2/9/2023
5.0.0 602 1/24/2023
4.0.1 852 12/21/2022
4.0.0 1,187 11/9/2022
3.4.1 1,702 10/20/2022
3.4.0 1,230 9/27/2022
3.3.1 3,243 6/8/2022
3.3.0 583 6/7/2022
3.2.0 2,324 4/1/2022
3.1.0 1,060 3/30/2022
3.0.0 5,637 2/21/2022
2.0.0 1,713 12/3/2021
1.3.0 2,856 11/25/2021
1.2.1 1,119 11/4/2021
1.2.0 2,047 9/29/2021
1.1.0 1,529 8/18/2021
1.0.1 1,587 4/22/2021
1.0.0 1,011 3/31/2021