1.2.0

New version of API Framework has been released with plenty of new features:

• Endpoint Caching API
• API Version Matching behavior
• Multiple configuration files
• Configure folder for API Plugins downloaded from Nuget

New features:

Endpoint Caching API

It's now possible to easily add caching support into your APIs. This new version provides IEndpointCache which can be injected where needed. It is Endpoint specific, so keys shouldn't collide with other endpoints.

IApiCache is available for more advanced scenarios.

Here's an example API where the new service is used: https://github.com/weikio/ApiFramework/blob/main/tests/Apis/HelloWorld/HelloWorldCacheApi.cs

API Version Matching behavior

Previously API Framework was very strict about API and Endpoint version numbers. If you had API with version 2.0.0.0 and your Endpoint asked for 2.0.0, it didn't work as exact match was expected.

Now, the exact matching is still enabled by default to make sure there isn't any breaking changes. But please note, in API Framework 2.0.0 the version matching will be changed to more lax by default.

API Framework now uses Nuget.Core's functionality when trying to locate an API for an Endpoint. The matching behavior is configurable using ApiVersionMatchingBehaviour:

public enum ApiVersionMatchingBehaviour
{
    OnlyExact,
    Lowest,
    HighestPatch,
    HighestMinor,
    Highest,
}

OnlyExact is same as previously and it is the current default. Lowest will be the default in the next major release.

The following document provides some advice on how these different options work: https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution

To configure the matching behaviour in your application, use ApiFrameworkAspNetCoreOptions:

        services.AddApiFrameworkStarterKit(options =>
        {
            options.ApiVersionMatchingBehaviour = ApiVersionMatchingBehaviour.Lowest;
        });

Multiple configuration files

API Framework's Endpoints and APIs uses the default IConfiguration mechanism. If everything is added into appsettings.json, the configuration file can get rather long. This why it is possible to add API Framework specific configuration file by calling AddApiFrameworkJsonConfigurationFile when building the host:

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        return WebHost.CreateDefaultBuilder(args)
            .AddApiFrameworkJsonConfigurationFile()
            .UseStartup<Startup>();
    }

Previously this supported only one file and defaulted to "apiframework.json". "apiframework.json" is still the default, but what is new is that the apiframework.json can be split into multiple files. Weikio.ApiFramework.Samples.JsonConfiguration shows an example of this where each endpoint has its own configuration file in the Config-folder.

Paths and wildcards can be used when defining the loaded configuration files, so all of these are supported:

        return WebHost.CreateDefaultBuilder(args)
            .AddApiFrameworkJsonConfigurationFile("Config")
            .AddApiFrameworkJsonConfigurationFile("Config/api*.json")
            .AddApiFrameworkJsonConfigurationFile(@"c:\temp")
            .AddApiFrameworkJsonConfigurationFile(@"c:\temp\*.json")
            .UseStartup<Startup>();

Configure folder for API Plugins downloaded from Nuget

API Framework APIs can be installed using Nuget. Previously these were (and still are, by default) installed into a temporary folder:

Path.Combine(Path.GetTempPath(), "NugetPackagePluginCatalog", Path.GetRandomFileName()

This happened automatically in Plugin Framework and couldn't be configured from API Framework. Problematic is that some APIs take a lot of disk space.

Now in the new release it is possible to configure where the APIs from Nuget are installed. This happens through PluginFrameworkApiProviderOptions.GetNugetApiInstallRoot. Here's an example of configuring this:

        services.Configure<PluginFrameworkApiProviderOptions>(options =>
        {
            options.GetNugetApiInstallRoot = (package, version, serviceProvider) =>
            {
                var result = Path.Combine(AppContext.BaseDirectory, "plugins", "apis", $"{package}.{version}");

                return result;
            };
        });

Which gives us the following result:

Please note: By default the plugins are still installed into the temp-directory to make sure there are no breaking changes. But also note that the default will be changed in the next major release.

Next stop is making sure that the plugins are downloaded only once, not every time the application starts.