“Everything is an OpenAPI” in ASP.NET Core: Introducing API Framework – Add Runtime Changes & Reusability & Plugins into Web Apps

September 23. 2021 0 Comments

Share on Twitter

Logo API Framework is a new open source project (Apache License 2.0) for ASP.NET Core with the aim of bringing more flexibility and more options to building ASP.NET Core based OpenAPI backends. With API Framework your code and your resourcesbecome the OpenAPI endpoints.

With API Framework the endpoints can be build using POCOs, Roslyn Script and Delegates and the reusable APIs can be distributed as plugins using Nuget. The APIs can be added runtime, without having to restart or to rebuild the application. The flexible plugin system with a built-in support for plugins means that API Framework can be used as the secure OpenAPI gateway into other systems. With plugins you can generate OpenAPI endpoints from databases, file systems, Azure blob storage, and more.

API Framework version 1.0.0 is now available from Nuget: https://www.nuget.org/packages/weikio.apiframework.aspnetcore. The project’s home pages is available from https://weik.io/apiframework.

Main Features

“Everything is an OpenAPI” mentality means that there’s multiple ways of building your backend’s endpoints. Plain C# and delegates are supported but so are your database and your browser and many more. Your code and your resources are the OpenAPI endpoints.

You can also integrate API Framework with your existing Controller & Action based app. API Framework is built on top of the MVC-functionality meaning it can take advantage of many of the features provided by ASP.NET Core.

Here’s a short summary of the major features of API Framework:

Everything is an OpenAPI:The API can be anything: Database, local files. Even the web browser. APIs can be created with C#, Roslyn Scripts and using delegates. These endpoint provide the full OpenAPI specs, meaning if you have a table called Inventory in your database, your OpenAPI specification will have the same Inventory available for use.
Runtime Changes: APIs and endpoints can be configured runtime, when the application is running. No need to restart the system to add a new endpoint.
Plugin Support:API Frameworks supports plugins. Nuget.org contains multiple ready made plugins, like SQL Server and Local Files. Custom plugins can be created and shared using Nuget.

There’s many more features, including support for health checks and async JSON streams. More information is available from the project’s home pages.

Terminology & Main Concepts

With API Framework there’s two main concepts:

API

In API Framework each API has two properties: Name and Version. And the actual functionality they provide.

Most often API is a C# class or a .NET type. But you can also use assemblies, Nuget packages, Roslyn scripts and delegates as APIs. Often the aim is to make APIs reusable and they can be shared using Nuget.

Endpoint

An API itself is not accessible through a web request. That's the work of an Endpoint. Endpoint gives your API a route (for example '/helloworld') and a configuration (if needed).

You can create multiple endpoints from each API and every endpoint can have different configuration.

Quick Start

Here’s a quick start, adapted from the documentation at https://docs.weik.io/apiframework/quickstart.html. The starting point is a blank ASP.NET Core 3.1 web api app.

This quick start shows how to build integration/data hub style backend using API Framework’s plugins. When the quick start is ready, we have an ASP.NET Core based backend which provides access to SQL Server and to an another OpenAPI backend (the PetShop).

In this quick start the APIs and Endpoints are added through code. Configuration through appsettings.json (IConfiguration) and through runtime REST endpoints are also supported.

1. Add the required package for API Framework:

        <PackageReference Include="Weikio.ApiFramework.AspNetCore.StarterKit" Version="1.0.0"/>

2. Add the SQL Server and OpenAPI plugins:

        <PackageReference Include="Weikio.ApiFramework.Plugins.SqlServer" Version="2.0.0" />
        <PackageReference Include="Weikio.ApiFramework.Plugins.OpenApi" Version="1.0.0" />

3. Modify Startup.Configure by adding API Framework & required APIs and Endpoints:

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddApiFrameworkStarterKit()
                .AddOpenApi("/pets", new ApiOptions()
                {
                    SpecificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json",
                    ApiUrl = "https://petstore3.swagger.io/api/v3"
                })
                .AddSqlServer("/eshop",
                    new SqlServerOptions()
                    {
                        // This provides a read only access to the db used in the documentations
                        ConnectionString =
                            "Server=tcp:adafydevtestdb001.database.windows.net,1433;User ID=docs;Password=3h1@*6PXrldU4F95;Integrated Security=false;Initial Catalog=adafyweikiodevtestdb001;"
                    });
        }

4. Run the application, wait a few second (the endpoints are generated on the background) and navigate tohttps://localhost:5001/swagger

The SQL Server database can be queried and filtered and the OpenAPI specs contains the schema for the database:

Getting Started

The quick start above show one approach for using API Framework. Best way to learn more about API Framework is through the following resources:

Project’s home page at https://weik.io/ApiFramework
Project’s documentation at https://docs.weik.io/apiframework/
Project’s issue tracker and source code at https://github.com/weikio/ApiFramework

Use Cases

As API Framework adds more flexibility into building and running ASP.NET Core backends, there’s different use cases where it can be helpful:

24/7 Backends:API Framework can be used to create ASP.NET Core backends which can be updated runtime. APIs and endpoints can be added and updated when the system is running. As an example, it’s possible to install API through Nuget and then configure one or more endpoints based on that API. All this runtime.
Integration Layers:API Framework can be used as the secure OpenAPI gateway into other systems. With plugins you can generate OpenAPI endpoints from databases, file systems, Azure blob storage, and more. This is helpful in scenarios where you want build integration/data hub style application.
More options for building APIs:As mentioned, with API Framework it is possible to build APIs using Roslyn, Delegates and more. This means it is entirely possible to create a backend using a folder of Roslyn Script files.

Current Status

Today is the day of the 1.0.0 release. The work continues, especially with the samples and with documentation. Currently there’s about 12 samples available, showcasing many of the features but there’s more to add. The documentation is little farther behind.

Some of the plugins released today are more advanced than the others. For example the database plugins are quite advanced but something like the Files-plugin is currently very barebones.

Project Home

API Framework can be found from Github and from https://weik.io/ApiFramework.