Generic API Response Builder for common response schema, handling status codes results and response validation in ASP.NET Core.
$ dotnet add package HttpResponseBuilderHttpResponseBuilder is a NuGet package designed to standardize API responses in ASP.NET Core applications.
This package provides a common response schema, out-of-the-box methods to ensure success status codes,
and a helper method to validate and return appropriate status code results from controllers.
ApiResponse<T> to standardize your API responses.IActionResult based on the status code.Install the NuGet package:
Install-Package HttpResponseBuilder
Use the ApiResponse<T> model to structure your API responses:
using HttpResponseBuilder.Models;
[ApiController]
[Route("api/[controller]")]
public class SampleController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult GetItem(int id)
{
if (id <= 0)
{
var errorResponse = new ApiResponse<object>
{
IsSuccess = false,
Status = "error",
StatusCode = 400,
Error = new ApiError { Message = "Invalid ID provided." }
};
return new BadRequestObjectResult(errorResponse);
}
var item = new { Id = id, Name = "Sample Item" };
var successResponse = new ApiResponse<object>
{
IsSuccess = true,
Status = "success",
StatusCode = 200,
Data = item
};
return new OkObjectResult(successResponse);
}
}
The EnsureSuccessStatusCode method validates success responses and throws an exception if the response is not successful:
using HttpResponseBuilder.Models;
var response = new ApiResponse<string>
{
IsSuccess = true,
StatusCode = 200,
Data = "Operation completed successfully"
};
response.EnsureSuccessStatusCode(); // No exception is thrown
var failedResponse = new ApiResponse<string>
{
IsSuccess = false,
StatusCode = 500,
Error = new ApiError { Message = "Internal server error." }
};
try
{
failedResponse.EnsureSuccessStatusCode(); // Throws FailedResponseException
}
catch (FailedResponseException ex)
{
Console.WriteLine(ex.Message);
}
Use the ValidateAndReturn helper method to validate the status code and return appropriate IActionResult:
using HttpResponseBuilder.Builders;
[HttpPost]
public IActionResult CreateItem([FromBody] ItemDto item)
{
if (item == null)
{
var errorResponse = new ApiResponse<object>
{
IsSuccess = false,
StatusCode = 400,
Error = new ApiError { Message = "Item cannot be null." }
};
return ApiResponseBuilder.ValidateAndReturn(errorResponse);
}
var successResponse = new ApiResponse<ItemDto>
{
IsSuccess = true,
StatusCode = 201,
Data = item
};
return ApiResponseBuilder.ValidateAndReturn(successResponse);
}
You can include additional metadata using the Metadata property:
var response = new ApiResponse<object>
{
IsSuccess = true,
StatusCode = 200,
Metadata = new MetaData
{
Timestamp = DateTime.UtcNow,
AdditionalInfo = "Processed successfully"
}
};
The HttpResponseBuilder library includes exceptions for handling specific scenarios:
FailedResponseException: Thrown when a response status code is invalid or indicates failure.Example:
try
{
var apiResponse = new ApiResponse<object> { IsSuccess = false, StatusCode = 404 };
apiResponse.EnsureSuccessStatusCode();
}
catch (FailedResponseException ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
A sample unit test project is included to help test and understand the usage of this package. To test:
HttpResponseBuilder NuGet package.We welcome contributions! Please fork this repository, make your changes, and submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.