Create Integration Layers using Plugins

The plugins in API Framework makes it simple to build integration layers / data hubs which provide access to your systems through a single OpenAPI endpoint. This how-to guide introduces the Plugin-system available in API Framework.

Introduction

In this guide we will create an OpenAPI backend which provides access to two external systems:

• SQL Azure based database (Adventureworks)
• External OpenAPI based web service (PetStore)

The end result will look like the following:

The access to these systems is created by using the SQL Server and OpenAPI plugins for API Framework. Both access points are configured so that not full access is provided: Only few tables from the DB is exposed and to PetStore only GET-access is provided.

This guide will show the usage of two plugins, both available from Nuget.org:

The SQL Server plugin allows you to securily expose your SQL Server database (or parts of it) through an OpenAPI endpoint. The OpenAPI plugin works as a proxy, allowing you to expose an another OpenAPI endpoint as-is or by allowing for example readonly access.

Current list of available plugins for API Framework is available from Nuget.org:

https://www.nuget.org/packages?q=Weikio.ApiFramework.Plugins

Creating the project

Api Framework can be installed into an existing ASP.NET Core app. It works together with Controllers and Actions. For a new backend, Web Api template is a good starting point. ConfigureServices is used to add Api Framework into app.

This guide used the ASP.NET Core Web Application and its API template as the starting point:

Please note: API Framework currently target the LTS version of .NET Core, meaning .NET Core 3.1. Please select that version as the SDK:

This guide uses API Framework's Starter Kit. For an explanation of the differences between Weikio.ApiFramework.Core, Weikio.ApiFramework.AspNetCore and Weikio.ApiFramework.AspNetCoreStarterKit, please see the FAQ.

Starter Kit is available as a Nuget package:

Start by installing the package and then adding API Framework into your application using ConfigureServices in Startup.cs:

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

AddApiFrameworkStarterKit is available from namespace Weikio.ApiFramework.AspNetCore.StarterKit:

using Weikio.ApiFramework.AspNetCore.StarterKit;

As explained in FAQ, the Starter Kit installs NSwag. If you now start the application and navigate to /swagger, you should see the Swagger UI and three different documents: Api, Admin and All:

Using the SQL Server Plugin

The SQL Server plugin for API Framework is available through Nuget.org.

Start by adding the SQL Server plugin:

<PackageReference Include="Weikio.ApiFramework.Plugins.SqlServer" Version="1.1.0-alpha.0.8"/>

The SQL Server plugins provides an extension method which makes it easier to use the plugin in your application.

Use ConfigureServices to add the SQL Server API into the backend and to create an endpoint:

services.AddApiFrameworkStarterKit()
    .AddSqlServer("/adventures", new SqlServerOptions()
    {
        ConnectionString = "Server=tcp:adafydevtestdb001.database.windows.net,1433;User ID=docs;Password=3h1@*6PXrldU4F95;Integrated Security=false;Initial Catalog=adafyweikiodevtestdb001;"
    });

And that's it. This provides a full read access to the DB. Make sure that things work by running the application:

As you can see, the plugin doesn't just provide a single query-method but instead you get access to the full database schema converter to OpenAPI schema:

Next we will add an external OpenAPI into our backend using the API Framework's OpenAPI plugin.

Using the OpenAPI Plugin

The API Framework's OpenAPI plugin provides a proxy to an another OpenAPI endpoint. Start by adding the OpenAPI plugin:

<PackageReference Include="Weikio.ApiFramework.Plugins.OpenApi" Version="1.0.0-alpha.0.23"/>

Same as the SQL Server plugin, OpenAPI plugin provides an extension method which makes it easier to use the plugin through ConfigureServices. Here's the modified code which adds the PetStore's OpenAPI endpoint into our backend:

services.AddApiFrameworkStarterKit()
    .AddSqlServer("/adventures",
        new SqlServerOptions()
        {
            ConnectionString =
                "Server=tcp:adafydevtestdb001.database.windows.net,1433;User ID=docs;Password=3h1@*6PXrldU4F95;Integrated Security=false;Initial Catalog=adafyweikiodevtestdb001;"
        })
    .AddOpenApi("/petstore",
        new ApiOptions() { SpecificationUrl = "https://petstore.swagger.io/v2/swagger.json" });

And here's the result after running the app:

We get full access to PetStore's OpenAPI endpoint and we can see the full schema with its documentation and all:

Configuring plugins to provide only a partial access to external systems

Both the SQL Server plugin and the OpenAPI plugin can be configured to provide only a partial access to external system. This is useful in scenarios where you would like to provide an external access to your DB (for example for reporting) and you want to limit the tables the user will see.

We will change the plugin configurations to enable the following two limitations:

• Only Product* tables will be visible through the SQL Server endpoint
• Only GET-access is provided to the PetStore.

The SQL Server plugin's options can be used to configure the excluded or included tables. In addition, you can create "dynamic" (or views) by providing the SQL query manually. To limit the access to only to the tables which start with Product, we can use the Tables-property:

services.AddApiFrameworkStarterKit()
    .AddSqlServer("/adventures",
        new SqlServerOptions()
        {
            Tables = new[] { "Product*" },
            ConnectionString =
                "Server=tcp:adafydevtestdb001.database.windows.net,1433;User ID=docs;Password=3h1@*6PXrldU4F95;Integrated Security=false;Initial Catalog=adafyweikiodevtestdb001;"
        })

This will result in:

To limit the access to PetStore, we can use ApiOptions provided by the plugin. These options allow us to limit the method, transform names and more. Here's the configuration which limits the access to only GET-methods:

.AddOpenApi("/petstore",
    new ApiOptions()
    {
        SpecificationUrl = "https://petstore.swagger.io/v2/swagger.json", 
        IncludeHttpMethods = new[] { "GET" }
    });

To make things even more interesting, we add a second endpoint to the petstore, which provides only write access to data:

.AddOpenApi("/petstore_writeonly",
    new ApiOptions()
    {
        SpecificationUrl = "https://petstore.swagger.io/v2/swagger.json", 
        ExcludeHttpMethods = new[] { "GET" }
    });

The full source code for the ConfigureServices is:

services.AddApiFrameworkStarterKit()
    .AddSqlServer("/adventures",
        new SqlServerOptions()
        {
            Tables = new[] { "Product*" },
            ConnectionString =
                "Server=tcp:adafydevtestdb001.database.windows.net,1433;User ID=docs;Password=3h1@*6PXrldU4F95;Integrated Security=false;Initial Catalog=adafyweikiodevtestdb001;"
        })
    .AddOpenApi("/petstore",
        new ApiOptions()
        {
            SpecificationUrl = "https://petstore.swagger.io/v2/swagger.json", 
            IncludeHttpMethods = new[] { "GET" }
        })
    .AddOpenApi("/petstore_writeonly",
        new ApiOptions()
        {
            SpecificationUrl = "https://petstore.swagger.io/v2/swagger.json", 
            ExcludeHttpMethods = new[] { "GET" }
        });

With the following result:

Source Code

Source code for this sample is available from GitHub: https://github.com/weikio/ApiFramework.Samples/tree/main/howtos/2_UsingPlugins

Summary & Next Steps

This guide introduced the following concepts:

• Using existing plugins in API Framework
• Using the SQL Server plugin
• Using the OpenAPI plugin

The plugins in API Framework makes it simple to build integration layers / data hubs which provide access to your systems through a single OpenAPI endpoint. You can expand this by adding security policies, health checks and more into your endpoints. And instead of defining the APIs and Endpoints in the code, you could use configuration file.

The next how-to guide will introduce the API Framework's support for doing runtime changes. API Framework supports adding new APIs and Endpoints runtime.