|
| 1 | +--- |
| 2 | +title: "Web API template" |
| 3 | +layout: default |
| 4 | +--- |
| 5 | + |
| 6 | +# Web API Project Template |
| 7 | + |
| 8 | +## Create Your First Arcus Web API Project |
| 9 | + |
| 10 | +First, install the template from NuGet: |
| 11 | + |
| 12 | +```shell |
| 13 | +> dotnet new install Arcus.Templates.WebApi |
| 14 | +``` |
| 15 | + |
| 16 | +When installed, the template can be created with shortname: `arcus-webapi`: |
| 17 | + |
| 18 | +```shell |
| 19 | +> dotnet new arcus-webapi --name Arcus.Demo.WebAPI |
| 20 | +``` |
| 21 | + |
| 22 | +## Features |
| 23 | + |
| 24 | +Creates a starter web API project with by default configured: |
| 25 | + |
| 26 | +* Arcus secret store setup with Azure Key Vault secret source ([docs](https://security.arcus-azure.net/features/secret-store)) |
| 27 | +* Application configuration with environment variables |
| 28 | +* Basic health endpoint with [ASP.NET Core health checks](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-2.2) with [OpenAPI support](https://www.codit.eu/blog/documenting-asp-net-core-health-checks-with-openapi/). |
| 29 | +* HTTP request tracking with default route `/` omitted ([docs](https://webapi.arcus-azure.net/features/logging)) |
| 30 | +* HTTP correlation ([docs](https://webapi.arcus-azure.net/features/correlation)) |
| 31 | +* Global exception handling ([docs](https://webapi.arcus-azure.net/features/logging)) |
| 32 | +* Docker building file |
| 33 | +* Swagger OpenAPI setup |
| 34 | +* Serilog setup with Application Insights logging sink ([docs](https://observability.arcus-azure.net/Features/sinks/azure-application-insights)) |
| 35 | +* Default JSON serialization |
| 36 | + |
| 37 | +### Configuration |
| 38 | + |
| 39 | +And additional features available with options: |
| 40 | + |
| 41 | +* `-au|--authentication` (default `None`) |
| 42 | + * `SharedAccessKey`: adds [shared access key authentication](https://webapi.arcus-azure.net/features/security/auth/shared-access-key) mechanism to the API project |
| 43 | + * `Certificate`: adds [client certificate authentication](https://webapi.arcus-azure.net/features/security/auth/certificate) mechanism to the API project |
| 44 | + * `JWT`: adds JWT (JSON Web Token) authentication mechanism to the API project |
| 45 | + * `None`: no authentication configured on the API project. |
| 46 | +* `-ia|--include-appsettings` (default `false`): includes a `appsettings.json` file to the web API project. |
| 47 | +* `-ec|--exclude-correlation` (default `false`): excludes the [capability to correlate](https://webapi.arcus-azure.net/features/correlation) between HTTP requests/responses from the API project. |
| 48 | +* `-eo|--exclude-openApi` (default `false`): exclude the [ASP.NET OpenAPI docs generation and UI](https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio) from API project. |
| 49 | +* `-lo|--logging` (default `Serilog`) |
| 50 | + * `Console`: no extra logging mechanism except for the default console logging will be added to the web API project. |
| 51 | + * `Serilog`: adds [Serilog](https://serilog.net/) as logging mechanism with request logging, default enrichers ([version](https://observability.arcus-azure.net/features/telemetry-enrichment#version-enricher), [application](https://observability.arcus-azure.net/features/telemetry-enrichment#application-enricher), and [correlation](https://webapi.arcus-azure.net/features/telemetry) when appropriate), sinking to Application Insights to the web API project. |
| 52 | + |
| 53 | +### Security |
| 54 | + |
| 55 | +As part of this template the following HTTP header(s) are removed for security sake: |
| 56 | +* `Server` header * Provides information concerning the Web API runtime |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +### Health |
| 61 | + |
| 62 | +A default health controller is available that exposes the configured health checks as an aggregated health report. |
| 63 | +For more information on application health, see [Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks). |
| 64 | + |
| 65 | +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. |
| 66 | +This way the application's health can be exposed in a safe manner without also exposing exception and assembly information to the user. |
0 commit comments