Read this document in different languages : Türkçe

ARConsistency

ARConsistency maintains response consistency by ensuring that all responses sent to the client for .Net Core Web Api projects are forwarded with the same template.

Setup

1. Install the Nuget Package

You can include this library in your project with the Nuget package.

Add the nuget package to your project using Package Manager Console or Nuget Package Manager.

PM> Install-Package ARConsistency

Or using .Net Cli

> dotnet add package ARConsistency

2. Settings

Add the following configuration to the "appsettings.json" file of your project.

"ApiConsistency": {
  "IsDebug": true,
  "ShowStatusCode": true,
  "ShowApiVersion": false,
  "ApiVersion": "1.0",
  "IgnoreNullValue": true,
  "UseCamelCaseNaming": true,
  "EnableExceptionLogging": true
}

Note: If you wish, you can assign these settings manually in the next step without reading them from the config file. This step is optional.

3. Startup Implementation

Add the following into "Startup.cs".

public void ConfigureServices(IServiceCollection services)
{
  // ...
  services.AddControllers()
      .AddApiResponseConsistency(options =>
      {
          Configuration.GetSection("ApiConsistency").Bind(options.ResponseOptions);
      });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
  app.UseApiResponseConsistency();
  // ...
}

Sample #1

public IActionResult Get()
{
  return Ok(_astronauts.FirstOrDefault());
}

Response

{
  "statusCode":  200,
  "isError":  false,
  "payload":  {
    "Id":  1,
    "Name":  "Neil",
    "Surname":  "Armstrong"
  }
}

Sample #2

public IActionResult Get()
{
  return new ApiResponse("Request successful.", _astronauts.FirstOrDefault(), 200, "2.0");
}

Response

{
  "statusCode":  200,
  "version":  "2.0",
  "message":  "Request successful.",
  "isError":  false,
  "payload":  {
    "Id":  1,
    "Name":  "Neil",
    "Surname":  "Armstrong"
  }
}

Response Types

ARConsistency works with three types of responses of its own. The basic information of these classes are as follows.

Class Name	HTTP Status Code	Description
ApiResponse	200 (OK)	It provides data return for successful response.
ApiError	400 (BadRequest)	Report any error to the client
ApiException	500 (Internal Server Error)	Throws errors and terminates the operation of the current procedure.

In addition to these response types, ARConsistency also supports basic web api return types such as Ok(), BadRequest(). But Ok() return type contains only the data ApiResponse can contain information such as Message in addition to the returned data.

The HTTP Status Codes in the table above are default values and can be changed during use.

Exception Handler

With the ARConsistency, you can use the ApiException response type to return an error with the HTTP status code you set.

All types of exceptions handled except ApiException are converted to ApiException and returned to the client with 500 (Internal Server Exception) HTTP status code.

The Enable Exception Logging setting must be turned on to support all types of exception. (see:Error Logging)

In custom exception types, you can use ExceptionStatusCodeHandler to return a different status code instead of 500.

To do so, define ExceptionStatusCodeHandler in "Startup.cs".

public void ConfigureServices(IServiceCollection services)
{
  // ...
  services.AddControllers()
      .AddApiResponseConsistency(options =>
      {
          // other options... (see:Startup Implemantation)
          options.ExceptionStatusCodeHandler.RegisterStatusCodedExceptionBaseType<IStatusCodedException>(type => type.StatusCode);
      });
}

IStatusCodedException Interface must contain a status code property of type int, and the classes implementing this interface must derive from the System.Exception class. (Interface and status code property names can be freely determined)

Sample:

public class ItemNotFoundException: Exception, IStatusCodedException
{
    public ItemNotFoundException(string message)
        : base(message)
    {
    }

    public int StatusCode => 400;
}

When the ItemNotFoundException exception is thrown, ARConsistency will convert this exception to ApiException and return the 400 status code specified in the error class.

Exception Logging

ARConsistency has the ability to log errors it captures with the ILogger interface. This setting (EnableExceptionLogging) is enabled by default unless you change it.

While this setting is on, errors occurring in the pipeline are transmitted to the logging mechanism via the ILogger interface and the summary of the error message is returned to the user as ApiExcepiton type api response. If the IsDebug option is on, the details of the error message are also included in the response.

When logging is turned off, error messages captured are thrown without processing.

Client-Side Usage

If you are sending a request from your .Net project to an API that uses ARConsistency, you need to deserialize the incoming serialized response with the ARConsistency base response model. You don't need to reference the ARConsistency package to your client project for this. Instead, you can use the ARConsistency.Abstractions library, which is lighter and contains only the basic base response model.

Responses returned by ARConsistency are serialized with generic ConsistentApiResponse class.

1. Install Package From NuGet

PM> Install-Package ARConsistency.Abstractions

2. Deserialize The Consistent Response

public async Task<AstronautDto> GetIdByAsync(int id)
{
  // other codes...

  var responseHttpMessage = await HttpClient.GetAsync(urlPath);
  string resultContent = await responseHttpMessage.Content.ReadAsStringAsync();

  var jsonSerializerOptions = new JsonSerializerOptions()
  {
      PropertyNameCaseInsensitive = true // use if UseCamelCaseNaming option is true in the ARConsistency config.
  };

  var response = JsonSerializer.Deserialize<ConsistentApiResponse<AstronautDto>>(resultContent, jsonSerializerOptions);
  return response.Payload;
}

In the above example, System.Text.Json namespace is used. You can also use third party (Newtonsoft.Json etc.) libraries.

If you wish, you can create your own response model in your project and deserialize the returned responses without using the ARConsistency.Abstractions library.

Test Api Documentation

There is a .Net Core Web Api project in the repository where you can test the project. You can find the Postman documentation of the test api here.

Contributing

Please browse the CONTRIBUTING.md file to contribute.