faysilalshareef/gateway-endpoint

Gateway Endpoint — REST to gRPC Bridge

Core Principles

• Gateway exposes REST endpoints that delegate to backend gRPC services
• Controllers inherit from a versioned ControllerBaseV1 abstract class (not raw ControllerBase)
• ControllerBaseV1 defines shared route constants and OpenAPI doc entries
• Controllers inject typed gRPC clients directly via primary constructors
• Request/response mapping is done inline in each action (no separate extension methods unless enum conversion is needed)
• Paginated<T> wraps list responses with Results, CurrentPage, PageSize, Total
• Command actions return a simple Response { Message } wrapper
• [Authorize] or [Authorize(Policy = ...)] or [Authorize(Roles = ...)] applied at class level

Key Patterns

ControllerBaseV1 — Shared Base Class

Every versioned controller inherits from this abstract base. It defines the default route constant, route prefix, and an OpenAPI doc entry for Scalar documentation.

namespace {Company}.Gateways.{Domain}.Controllers.V1;

[ApiController]
[ApiExplorerSettings(GroupName = "v1")]
[Authorize]
public abstract class ControllerBaseV1 : ControllerBase
{
    public const string DefaultRoute = "api/v1/[controller]";
    public const string RoutePrefix = "api/v1/";

    public static OpenApiDocEntry GetDocEntry() => new DevelopmentOpenApiDocEntry(
        Name: "v1",
        new() { Title = "{Domain} Management V1 API's", Version = "v1" });
}

Simple Query Controller — Direct gRPC Client Injection

Inject the gRPC client via primary constructor. Map gRPC response to REST DTO inline using Select.

namespace {Company}.Gateways.{Domain}.Controllers.V1;

[Route(DefaultRoute)]
[Authorize(Policy = Policy.Operator)]
public class ProductsController(
    ProductManagement.ProductManagementClient productClient) : ControllerBaseV1
{
    private readonly ProductManagement.ProductManagementClient _productClient = productClient;

    [HttpGet]
    public async Task<ActionResult<GetProductsOutput>> GetProductsAsync()
    {
        var response = await _productClient.FetchAllAsync(new EmptyRequest { });

        return Ok(new GetProductsOutput
        {
            Products = response.Products.Select(p => new ProductModel
            {
                Id = Guid.Parse(p.Id),
                Name = p.Name,
                Code = p.Code,
            })
        });
    }
}

Full CRUD Controller with Paginated Queries

Controllers that handle both commands and queries inject multiple gRPC clients. Command methods build gRPC request objects inline and return Response { Message }. Query methods map gRPC responses to output DTOs and wrap lists in Paginated<T>.

namespace {Company}.Gateways.{Domain}.Controllers.V1;

[Route(DefaultRoute)]
[Authorize(Roles = $"{Roles.SuperAdmin},{Roles.Admin}")]
public class OrdersController(
    OrderCommands.OrderCommandsClient commandsClient,
    OrderManagementQueries.OrderManagementQueriesClient queriesClient,
    ILogger<OrdersController> logger) : ControllerBaseV1
{
    private readonly OrderCommands.OrderCommandsClient _commandsClient = commandsClient;
    private readonly OrderManagementQueries.OrderManagementQueriesClient _queriesClient = queriesClient;
    private readonly ILogger<OrdersController> _logger = logger;

    [HttpPost("{id}")]
    public async Task<ActionResult<Response>> CreateOrder(
        Guid id, [FromBody] CreateOrderModel model)
    {
        var response = await _commandsClient.CreateOrderAsync(new CreateOrderRequest
        {
            Id = id.ToString(),
            Name = model.Name,
            Description = model.Description,
            StartDate = model.StartDate.ToTimestamp(),
            Status = (Proto.OrderStatus)model.Status,
            Items = { model.Items.Select(x => x.ToString()) },
        });

        return new Response { Message = response.Message };
    }

    [HttpPut("{id}")]
    public async Task<ActionResult<Response>> UpdateOrderAsync(
        Guid id, [FromBody] UpdateOrderModel model)
    {
        var response = await _commandsClient.UpdateOrderAsync(new UpdateOrderRequest
        {
            Id = id.ToString(),
            Name = model.Name,
            Description = model.Description,
        });

        return new Response { Message = response.Message };
    }

    [HttpGet]
    public async Task<ActionResult<Paginated<OrderOutput>>> GetOrdersAsync(
        [FromQuery] GetOrdersFilterModel filterModel)
    {
        var response = await _queriesClient.GetOrdersAsync(new GetOrdersRequest
        {
            PageSize = filterModel.PageSize,
            CurrentPage = filterModel.CurrentPage,
            StartDateFrom = filterModel.StartDateFrom.ToTimestamp(),
            StartDateTo = filterModel.StartDateTo.ToTimestamp(),
            Status = (QueryProto.OrderStatus)filterModel.Status,
        });

        var output = response.Orders.Select(x => new OrderOutput
        {
            Id = Guid.Parse(x.Id),
            Name = x.Name,
            Description = x.Description,
            StartDate = x.StartDate.ToDateTime(),
            Status = (Models.Enums.OrderStatus)x.Status,
        });

        return new Paginated<OrderOutput>(
            output, response.CurrentPage, response.PageSize, response.Total);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<OrderDetailOutput>> GetOrderAsync(Guid id)
    {
        var response = await _queriesClient.GetOrderDetailsAsync(
            new GetOrderDetailsRequest { Id = id.ToString() });

        return new OrderDetailOutput
        {
            Order = new OrderOutput
            {
                Id = Guid.Parse(response.Order.Id),
                Name = response.Order.Name,
                StartDate = response.Order.StartDate.ToDateTime(),
                Status = (Models.Enums.OrderStatus)response.Order.Status,
            },
            Items = response.Items.Select(Guid.Parse),
        };
    }
}

gRPC Error Handling in Controllers

For specific endpoints needing custom error handling, catch RpcException and return ProblemDetails. The global HttpResponseExceptionFilter handles most cases automatically.

[HttpGet("items")]
[ProducesResponseType(typeof(Paginated<ItemOutput>), StatusCodes.Status200OK)]
public async Task<ActionResult<Paginated<ItemOutput>>> GetItemsAsync(
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 20,
    [FromQuery] string? searchName = null)
{
    try
    {
        var request = new GetItemsRequest { Page = page, PageSize = pageSize };

        if (!string.IsNullOrEmpty(searchName))
            request.SearchName = searchName;

        var response = await _queriesClient.GetItemsAsync(request);

        return Ok(new Paginated<ItemOutput>(
            response.Items.Select(i => i.ToItemOutput()),
            response.Page, response.PageSize, response.TotalCount));
    }
    catch (RpcException ex)
    {
        _logger.LogError(ex,
            "gRPC error in {Method} -- StatusCode: {StatusCode}",
            nameof(GetItemsAsync), ex.StatusCode);

        return StatusCode(StatusCodes.Status502BadGateway, new ProblemDetails
        {
            Title = "Upstream service error",
            Detail = ex.Status.Detail,
            Status = StatusCodes.Status502BadGateway
        });
    }
}

Paginated Response Model

namespace {Company}.Gateways.Common.Models;

public class Paginated<TItem>(
    IEnumerable<TItem> results, int currentPage, int pageSize, int total)
{
    public IEnumerable<TItem> Results { get; } = results;
    public int CurrentPage { get; } = currentPage;
    public int PageSize { get; } = pageSize;
    public int Total { get; } = total;
    public int LastPage => PageSize == 0 ? 0
        : Total % PageSize <= 0 ? Total / PageSize
        : (Total / PageSize) + 1;
}

Response Model for Commands

namespace {Company}.Gateways.{Domain}.Models;

public class Response
{
    public required string Message { get; set; }
}

Request/Response DTOs

Request models use class with required properties. Output models follow the same pattern.

namespace {Company}.Gateways.{Domain}.Models.Requests;

public class CreateOrderModel : UpdateOrderModel
{
    public required List<Guid> Items { get; init; }
    public required List<DateTime> Dates { get; init; }
}

namespace {Company}.Gateways.{Domain}.Models.Responses;

public class OrderOutput
{
    public required Guid Id { get; init; }
    public required string Name { get; init; }
    public required string Description { get; init; }
    public required DateTime StartDate { get; init; }
    public required OrderStatus Status { get; init; }
}

Enum Mapping Extensions (Only When Needed)

Separate extension methods only for enum conversions between proto and domain types.

namespace {Company}.Gateways.{Domain}.Extensions;

using CommandProto = {Company}.{Domain}.GrpcClients.Protos.Commands;
using QueryProto = {Company}.{Domain}.GrpcClients.Protos.Queries;

public static class OrderExtensions
{
    public static CommandProto.ItemType ToProtoEnum(this Models.Enums.ItemType itemType)
        => itemType switch
        {
            Models.Enums.ItemType.Physical => CommandProto.ItemType.Physical,
            Models.Enums.ItemType.Digital => CommandProto.ItemType.Digital,
            _ => throw new ArgumentOutOfRangeException(nameof(itemType))
        };

    public static Models.Enums.ItemType ToDomainEnum(this QueryProto.ItemType itemType)
        => itemType switch
        {
            QueryProto.ItemType.Physical => Models.Enums.ItemType.Physical,
            QueryProto.ItemType.Digital => Models.Enums.ItemType.Digital,
            _ => throw new ArgumentOutOfRangeException(nameof(itemType))
        };
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Inheriting raw ControllerBase | Inherit ControllerBaseV1 with shared route/docs | | Separate mapping extension classes for all fields | Map inline in controller actions | | Business logic in gateway controller | Gateway only maps and delegates to gRPC | | Exposing gRPC proto types in REST response | Map to REST-specific DTOs | | Missing [Authorize] on controller class | Apply at class level, use Policy or Roles | | Constructor injection without backing field | Assign to private readonly field | | Returning raw gRPC response | Wrap in Response { Message } for commands |

Detect Existing Patterns

# Find gateway controllers
grep -r "ControllerBaseV1\|: ControllerBase" --include="*.cs" Controllers/

# Find gRPC client injection
grep -r "CommandsClient\|QueriesClient\|ManagementClient" --include="*.cs" Controllers/

# Find Paginated usage
grep -r "Paginated<" --include="*.cs"

# Find authorization attributes
grep -r "\[Authorize" --include="*.cs" Controllers/

Adding to Existing Project

1. Inherit ControllerBaseV1 and use [Route(DefaultRoute)]
2. Inject gRPC clients via primary constructor with backing readonly fields
3. Map inline in each action -- build gRPC request, map response to DTO
4. Return Paginated<T> for list endpoints using constructor args
5. Return Response { Message } for command endpoints
6. Apply [Authorize] at class level with Policy or Roles
7. Register gRPC clients via the endpoint-registration skill