API response consistency

The ApiResponseFilter is an action filter attribute that provides consistent structure to API responses. It wraps the API response body within an ApiResponse class.

/// <summary>
/// Api response
/// </summary>
public class ApiResponse
{
    /// <summary>
    /// Error messages
    /// </summary>
    public string[]? Errors { get; init; }

    /// <summary>
    /// Success flag
    /// </summary>
    public bool IsSuccess { get; init; }

    /// <summary>
    /// Response body
    /// </summary>
    public object? Data { get; init; }

    /// <summary>
    /// Status code
    /// </summary>
    public HttpStatusCode StatusCode { get; init; }
}

Model Validation

If the model state is invalid, the filter captures the errors and returns a structured error response with an HTTP status code of 400 Bad Request.

Installation

dotnet add package Eiffel.CrossCutting.ApiResponseConsistency

You should install Eiffel.CrossCutting.ApiResponseConsistency NuGet package into your application.

Usage

To apply this filter, decorate your controllers or actions with [ApiResponseFilter].

For better experience decorate your methodProducesDefaultResponseTypeand ProducesResponseTypeby using ApiResponse and ApiResponse<T> classes.

[ApiResponseFilter]
public class BookingController : ControllerBase
{
    [HttpPost]
    [ProducesDefaultResponseType(typeof(ApiResponse))]
    [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(ApiResponse<CreateBookingResponse>))]
    public async Task<CreateBookingResponse> PostAsync([FromBody] CreateBookingRequest request)
    {
        // Your implementation details..
    }
}

To appy this filter to all controllers in your application, add to Mvc filters.

// Program.cs (.NET5 and above)
public static async Task Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    
    // Applies api response filter for all controllers
    builder.Services.AddControllers(options =>
    {
        options.Filters.Add<ApiResponseFilter>();
    });
     
    var app = builder.Build();
    app.Run();
}

Disabling consistency for specific actions/controllers

If you don't want a particular action or controller to be wrapped with this consistency logic, decorate it with the DisableApiResponseConsistency attribute.

[DisableApiResponseConsistency]
public class FileController : ControllerBase
{
    [HttpPost]
    public async Task PostAsync(IFormFile file)
    {
        // Your implementation details..
    }
}