Skip to content

API Gateway: Routing Rules & gRPC Mapping

Version Date Author Change Description
1.0 2025-09-11 Senior Systems Analyst Initial draft based on the v2.0 REST and gRPC contracts for the Google SSO architecture.

1.0 Overview

This document provides the definitive mapping of incoming HTTP RESTful API requests to their corresponding backend gRPC service calls. The API Gateway uses these rules to perform routing, protocol translation, and permission checks. This serves as a technical blueprint for the gateway's core logic.

  • Pre-computation: For every request that requires authentication (i.e., not the login/callback endpoints), the gateway first performs a AuthService.ValidateSession call. If successful, it proceeds to the permission check and routing.
  • Permission Check: Before routing, the gateway performs an AuthService.CheckPermission call using the user_id from the session and the "Required Permission" specified in the table below.

2.0 Routing Table

HTTP Method REST Endpoint (/api/v1/...) Required Permission gRPC Service gRPC Method Notes
GET /auth/google/login None (Public) N/A N/A Gateway Logic Only. Generates a Google OAuth URL and performs an HTTP 302 redirect.
GET /auth/google/callback None (Public) AuthService HandleGoogleAuthCallback The authorization_code from the query string is passed as the request payload.
GET /users/me Authenticated User AuthService GetUser The user_id from the validated session is used in the gRPC request.
PUT /users/me Authenticated User AuthService UpdateUser The user_id from the validated session is used in the gRPC request.
POST /users/invite admin:user:invite AuthService InviteUser
GET /users admin:user:list AuthService ListUsers REST query parameters are mapped to the ListUsersRequest message fields.
GET /users/{userId} admin:user:list AuthService GetUser
PUT /users/{userId} admin:user:edit AuthService UpdateUser
GET /users/{userId}/effective-permissions admin:user:view_permissions AuthService GetUserEffectivePermissions
POST /roles admin:role:create AuthService CreateRole Note: CreateRole RPC needs to be added to the grpc_api_contract.md.
GET /roles admin:role:list AuthService ListRoles Note: ListRoles RPC needs to be added to the grpc_api_contract.md.
GET /roles/{roleId} admin:role:list AuthService GetRole Note: GetRole RPC needs to be added to the grpc_api_contract.md.
PUT /roles/{roleId} admin:role:edit AuthService UpdateRole Note: UpdateRole RPC needs to be added to the grpc_api_contract.md.
DELETE /roles/{roleId} admin:role:delete AuthService DeleteRole Note: DeleteRole RPC needs to be added to the grpc_api_contract.md.
POST /groups admin:group:create AuthService CreateGroup Note: CreateGroup RPC needs to be added to the grpc_api_contract.md.
GET /groups admin:group:list AuthService ListGroups Note: ListGroups RPC needs to be added to the grpc_api_contract.md.
GET /groups/{groupId} admin:group:list AuthService GetGroup Note: GetGroup RPC needs to be added to the grpc_api_contract.md.
PUT /groups/{groupId} admin:group:edit AuthService UpdateGroup Note: UpdateGroup RPC needs to be added to the grpc_api_contract.md.
DELETE /groups/{groupId} admin:group:delete AuthService DeleteGroup Note: DeleteGroup RPC needs to be added to the grpc_api_contract.md.
GET /audit-logs admin:audit:view AuthService ListAuditLogs Note: ListAuditLogs RPC needs to be added to the grpc_api_contract.md. REST query params mapped to request message.