Timezone Date Normalization API - .NET 8 Web API Example 🌍🕒

Overview

The Timezone Date Normalization API is a sample .NET 8 Web API designed to help developers manage date and time inputs across multiple time zones. This API normalizes DateTime, DateOnly, and nullable date inputs using a custom action filter that respects the user's time zone, which is sent via an HTTP header. This feature is crucial for preventing UTC shifting bugs in multi-tenant, multi-timezone applications built with Angular and .NET.

Features

• Custom Action Filter: Automatically normalizes date inputs based on the user's time zone.
• Multi-Tenant Support: Designed to handle applications serving multiple clients across different time zones.
• Date and Time Handling: Supports DateTime, DateOnly, and nullable date types.
• Robust Middleware: Easily integrates into existing .NET applications.
• Documentation: Includes Swagger for easy API exploration.

Table of Contents

• Installation
• Usage
• API Endpoints
• Custom Action Filter
• Middleware Setup
• Testing
• Contributing
• License
• Links

Installation

To get started with the Timezone Date Normalization API, follow these steps:

1. Clone the repository:

   git clone https://github.com/mussmdst/timezone-date-normalization-api.git
   cd timezone-date-normalization-api

2. Ensure you have .NET 8 SDK installed. You can download it from the official .NET website.

3. Restore the dependencies:

   dotnet restore

4. Run the application:

   dotnet run

5. Visit the Swagger UI at http://localhost:5000/swagger to explore the API.

Usage

To use the API, you need to send requests with the appropriate HTTP headers. The key header is X-Timezone, which specifies the user's time zone.

Example Request

POST /api/datetime
Content-Type: application/json
X-Timezone: America/New_York

{
  "date": "2023-10-01T12:00:00"
}

Example Response

{
  "normalizedDate": "2023-10-01T16:00:00Z"
}

API Endpoints

The API exposes several endpoints for date normalization:

Normalize DateTime

• Endpoint: POST /api/datetime
• Request Body:

  {
    "date": "2023-10-01T12:00:00"
  }

• Response: Normalized UTC date.

Normalize DateOnly

• Endpoint: POST /api/dateonly
• Request Body:

  {
    "date": "2023-10-01"
  }

• Response: Normalized UTC date.

Nullable Date

• Endpoint: POST /api/nullable-date
• Request Body:

  {
    "date": null
  }

• Response: Returns null if input is null.

Custom Action Filter

The custom action filter plays a vital role in normalizing date inputs. It intercepts incoming requests, reads the X-Timezone header, and adjusts the date values accordingly.

Implementation

public class TimezoneActionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        var timezoneHeader = context.HttpContext.Request.Headers["X-Timezone"].ToString();
        // Logic to normalize dates based on timezoneHeader
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        // Optional post-processing logic
    }
}

Middleware Setup

To integrate the custom action filter into your application, register it in the Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.Filters.Add<TimezoneActionFilter>();
    });
    services.AddSwaggerGen();
}

Testing

To ensure the API works as expected, unit tests are included. You can run the tests using:

dotnet test

Example Test Case

[Fact]
public void TestDateNormalization()
{
    // Arrange
    var controller = new DateTimeController();
    var request = new DateTimeRequest { Date = "2023-10-01T12:00:00" };
    
    // Act
    var result = controller.NormalizeDate(request);
    
    // Assert
    Assert.Equal("2023-10-01T16:00:00Z", result.NormalizedDate);
}

Contributing

Contributions are welcome! If you want to contribute to this project, please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/YourFeature).
3. Make your changes and commit them (git commit -m 'Add your feature').
4. Push to the branch (git push origin feature/YourFeature).
5. Create a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

For the latest releases, visit the Releases section.

Explore the API and its features in detail.