API Gateway Documentation

This document details the API Gateway service, a central component of the space trader elite-style backend. The gateway acts as a single entry point for all client requests, routing them to the appropriate microservice.

1. Architecture and Purpose

The API Gateway is built using ASP.NET Core with the YARP (Yet another Reverse Proxy) library. Its primary functions are:

Request Routing: It forwards incoming HTTP requests to one of the backend microservices (e.g., Galaxy, Player, Ship, Auth, Market, Mission).
Cross-Cutting Concerns: It handles tasks such as authentication, authorization, and CORS, centralizing these concerns away from individual microservices.
Security: It validates JWTs (JSON Web Tokens) and enforces role-based authorization policies.

2. Configuration

The core functionality of the gateway is configured in the appsettings.json file, which defines the routing rules and cluster destinations for each microservice.

2.1. JWT Configuration

The Jwt section defines the settings for handling JSON Web Tokens.

appsettings.json
{
    "Jwt": {
        "Key": "super-secure-secret-key-change-me-super-secure-secret-key-change-me",
        "Issuer": "AuthService",
        "Audience": "ClientApp",
        "ExpiresInMinutes": 15,
        "RefreshTokenExpiresInDays": 7
    },
    // ...
}

The gateway uses these settings to validate incoming JWTs, ensuring they are issued by the correct authority (AuthService) and intended for the correct audience (ClientApp).

2.2. Reverse Proxy Configuration

The ReverseProxy section is where routes and clusters are defined, telling the gateway how to forward requests to the downstream services.

appsettings.json
"ReverseProxy": {
    "Routes": {
        "ROUTE1": {
            "ClusterId": "CLUSTER_GALAXY",
            "Match": {
                "Path": "/galaxy/{*remainder}"
            }
        },
        // ... other routes
    },
    "Clusters": {
        "CLUSTER_GALAXY": {
            "Destinations": {
                "destination1": {
                    "Address": "http://moe_galaxyservice:8080/api/"
                }
            }
        },
        // ... other clusters
    }
}

This configuration routes any request matching the path /galaxy/{*remainder} to the CLUSTER_GALAXY. The CLUSTER_GALAXY is then configured to forward the request to the specified destination address, in this case, http://moe_galaxyservice:8080/api/.

3. API Endpoints

The API Gateway exposes a single, unified API surface. Requests are routed to the appropriate microservice based on the URL path.

3.1. Auth Service Endpoints

POST /auth/{*remainder}

Routes requests to the Authentication Service. This would typically be used for user login, registration, and token management.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/auth/`, which is forwarded to the auth service.

3.2. Galaxy Service Endpoints

GET /galaxy/{*remainder}

Routes requests to the Galaxy Service, likely for retrieving information about planets, systems, or star charts.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/galaxy/`.

3.3. Market Service Endpoints

GET /market/{*remainder}

Routes requests to the Market Service, which manages trade goods and market prices for various planets.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/market/`.

3.4. Mission Service Endpoints

GET /mission/{*remainder}

Routes requests to the Mission Service, used for managing and accepting missions.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/mission/`.

3.5. Player Service Endpoints

GET /player/{*remainder}

Routes requests to the Player Service, for managing player data, inventory, and stats.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/player/`.

3.6. Ship Service Endpoints

GET /ship/{*remainder}

Routes requests to the Ship Service, for managing player ships, upgrades, and cargo.

Parameter	Type	Description
`{*remainder}`	string	The rest of the path after `/ship/`.

4. Authorization Policies

The gateway defines several authorization policies based on user roles, which are extracted from the JWT.

AdminOnly: Requires the user to be authenticated and have the "Admin" role.
Users: Requires the user to be authenticated and have either the "User" or "Admin" role.

These policies can be applied to specific routes in the appsettings.json file to restrict access to certain services.

5. Docker and Deployment

The service includes a Dockerfile for containerization. The build process uses a multi-stage build:

Build Stage: Uses the mcr.microsoft.com/dotnet/sdk:9.0 image to restore dependencies and publish the application.
Final Stage: Uses the lighter mcr.microsoft.com/dotnet/aspnet:9.0 runtime image, copying only the published application files to create a small and secure final image.