Firetail.Net 1.0.6

Firetail .NET - Developed by https://github.com/mujahidq

Firetail .NET is a library designed to help developers build secure and robust APIs by leveraging the OpenAPI Specification (formerly known as Swagger Spec). It provides inline checking of API request parameters and comprehensive application logging of request and response payloads.

Firetail .NET allows you to define your API using an OpenAPI specification, then provides middleware to enforce aspects of that specification, ensuring your API behaves as intended.

Features

• Automated validation of incoming requests based on your OpenAPI specification.
• Automated validation of API responses against defined schemas.
• Comprehensive application logging of both request and response payloads.
• Sanitization of sensitive headers in logs.
• Serving of your OpenAPI/Swagger specification in JSON format.
• Support for API versioning through base paths.

Why Firetail .NET?

Firetail .NET encourages an API-first approach, where the API specification is written before implementation. This helps in clear communication of API functionality to all developers, even before coding begins, and ensures adherence to the defined contract.

How to Use

Prerequisites

• .NET 9.0+

Installing

Add the Firetail.Net NuGet package to your project.

Running

1. Load your OpenAPI Specification:
   Place your OpenAPI specification file (e.g., openapi.json or swagger.json) in your project.

2. Configure Services:
   In your Startup.cs or Program.cs, configure Firetail services:

// Program.cs or Startup.cs
public void ConfigureServices(IServiceCollection services)
{
   // ... other services
   services.AddFiretail(options =>
   {
      options.ApiDocPath = "path/to/your/openapi.json"; // Required: Path to your OpenAPI spec file
      options.FiretailAPIKey = "YOUR_FIRETAIL_API_KEY"; // Required: Your Firetail API Key
      options.FiretailAPIHost = "https://api.logging.eu-west-1.prod.firetail.app"; // Required: Firetail logging endpoint
      // Optional: Configure logging thresholds
      options.LogMaxItems = 1000;
      options.LogMaxSize = 950_000; // bytes
      options.LogMaxTimeMs = 5 * 1000; // milliseconds
      // Optional: Specify sensitive headers to scrub from logs
      options.SensitiveHeaders = new string[] { "Authorization", "X-Api-Key" };
   });
   // ... other services
}

3. Use Firetail Middleware:
   In your Startup.cs or Program.cs, add the Firetail middleware to your request pipeline:

// Program.cs or Startup.cs
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
   // ... other middleware
   app.UseFiretail();
   // ... other middleware
}

API Versioning and Base Path

Firetail .NET supports API versioning by recognizing the servers block in OpenAPI 3.x.x specifications or the basePath field in Swagger 2.0 specifications. The base path from your specification will be used to route requests.

Example OpenAPI 3.x.x servers block:

servers:
  - url: https://MYHOST/1.0
   description: full url example
  - url: /1.0
   description: relative path example

Example Swagger 2.0 basePath field:

basePath: /1.0

Swagger JSON

Firetail .NET makes your OpenAPI/Swagger specification available in JSON format. By default, it will be served at the base path of your API (e.g., /v1.0/openapi.json for OpenAPI 3.x.x or /v1.0/swagger.json for Swagger 2.0).

HTTPS Support

Firetail .NET runs within the ASP.NET Core environment. HTTPS configuration is handled at the ASP.NET Core application or web server level (e.g., Kestrel, IIS, Nginx). Refer to ASP.NET Core documentation for details on configuring HTTPS.

Logging

Firetail .NET automatically captures and logs API request and response payloads, along with rich metadata. Logs are sent to the configured Firetail API host.

Changes

A full changelog is maintained on the GitHub releases page.

Contributing

We welcome your ideas, issues, and pull requests. Please follow standard GitHub practices.