Web API Project Template

Create Your First Arcus Web API Project

First, install the template from NuGet:

> dotnet new --install Arcus.Templates.WebApi

When installed, the template can be created with shortname: arcus-webapi:

> dotnet new arcus-webapi --name Arcus.Demo.WebAPI

Features

Creates a starter web API project with by default configured:

• Arcus secret store setup with Azure Key Vault secret source (docs)
• Application configuration with environment variables
• Basic health endpoint with ASP.NET Core health checks with OpenAPI support.
• HTTP request tracking with default route / omitted (docs)
• HTTP correlation (docs)
• Global exception handling (docs)
• Docker building file
• Swagger OpenAPI setup
• Serilog setup with Application Insights logging sink (docs)
• Default JSON serialization

Configuration

And additional features available with options:

• -au|--authentication (default None)
  • SharedAccessKey: adds shared access key authentication mechanism to the API project
  • Certificate: adds client certificate authentication mechanism to the API project
  • JWT: adds JWT (JSON Web Token) authentication mechanism to the API project
  • None: no authentication configured on the API project.
• -ia|--include-appsettings (default false): includes a appsettings.json file to the web API project.
• -ec|--exclude-correlation (default false): excludes the capability to correlate between HTTP requests/responses from the API project.
• -eo|--exclude-openApi (default false): exclude the ASP.NET OpenAPI docs generation and UI from API project.
• -lo|--logging (default Serilog)
  • Console: no extra logging mechanism except for the default console logging will be added to the web API project.
  • Serilog: adds Serilog as logging mechanism with request logging, default enrichers (version, application, and correlation when appropriate), sinking to Application Insights to the web API project.

Security

As part of this template the following HTTP header(s) are removed for security sake:

• Server header * Provides information concerning the Web API runtime

The OpenAPI documentation is available by-default. Be careful of exposing sensitive information with the OpenAPI documentation, only expose what's necessary and hide everything else.

Health

A default health controller is available that exposes the configured health checks as an aggregated health report. For more information on application health, see Microsoft's documentation.

The controller doesn't directly exposes Microsoft's HealthReport model but uses a custom ApiHealthReport model which eliminates the exception details from the original report. This way the application's health can be exposed in a safe manner without also exposing exception and assembly information to the user.