Helldivers 2 API

When consuming source generators in a .NET project, you must configure the ProjectReference correctly so the compiler treats the referenced project as a source generator rather than a standard library. In this sample, the configuration is located in Helldivers_2_SourceGen.Sample.csproj.

<!-- Note: The specific XML attributes for the ProjectReference are found in Helldivers_2_SourceGen.Sample.csproj -->

The API uses an API key mechanism to allow certain clients to bypass standard rate limits. This feature is enabled by default but requires a 32-bit base64-encoded signing key.

Option 1: Disable API Authentication

If you do not want to use API keys (e.g., you are managing limits via standard configuration), disable authentication:

docker run -p 8080:8080 -e "Helldivers__API__Authentication__Enabled=false" helldivers2-api

Option 2: Enable API Authentication with a Signing Key

To use API keys, you must provide a signing key via the Helldivers__API__Authentication__SigningKey variable. The key must be 32 bits and base64 encoded.

docker run -p 8080:8080 -e "Helldivers__API__Authentication__SigningKey=YourSigningKey" helldivers2-api

For deeper technical knowledge on implementing and wiring source generators, refer to these resources:

• Video Tutorial: Let’s Build an Incremental Source Generator With Roslyn, by Stefan Pölz
• Official Documentation: Source Generators Cookbook

By default, OpenAPI specifications are not included in the container image. To enable OpenAPI support, use the OPENAPI=true build argument during the build process.

docker build --build-arg="OPENAPI=true" -f ./src/Helldivers-2-API/Dockerfile -t helldivers2-api .

Most API settings (rate limits, synchronization intervals, etc.) can be customized at runtime using environment variables. This overrides the values defined in appsettings.json.

To override a configuration key, use double underscores (__) as a delimiter for the hierarchy. For example, to override Helldivers:Synchronization:IntervalSeconds, use the environment variable Helldivers__Synchronization__IntervalSeconds.

Example: Setting the synchronization interval to 10 seconds:

docker run -p 8080:8080 -e "Helldivers__Synchronization__IntervalSeconds=10" helldivers2-api

You can self-host the API using Docker. This allows for running instances in secured networks or with modified settings like custom rate limits.

Prerequisites

Clone the repository including submodules:

git clone --recurse-submodules https://github.com/helldivers-2/api.git

Build Steps

Run the build command from inside the cloned folder:

docker build -f ./src/Helldivers-2-API/Dockerfile -t helldivers2-api .

Run the container

Start the container mapping port 8080:

docker run -p 8080:8080 helldivers2-api

WARNING

If you encounter System.ArgumentNullException: Value cannot be null. (Parameter 's') during startup, you must configure API keys using the steps in Configuring API keys for the self-hosted version.

To debug the source generator logic, you can use two primary methods:

1. Use the launchSettings.json profile provided in the Properties/ directory.
2. Debug the unit tests in the Helldivers_2_SourceGen.Tests project.

To help the community maintain the API and notify developers of breaking changes, you should include identification headers in your requests. While not currently mandatory, the X-Super-Client header will be made obligatory in the future.

Required/Recommended Headers

• X-Super-Client: The name of your application or domain (e.g., X-Super-Client: my-app-name).
• X-Super-Contact: (Optional) A way to contact you if your site lacks visible contact information. This is used to notify you of API changes or potential abuse restrictions.

GET /some-endpoint HTTP/1.1
Host: api.helldivers2.dev
X-Super-Client: my-awesome-app
X-Super-Contact: dev@example.com

By default, the API validates that all requests include the X-Super-Client and X-Super-Contact headers. If you receive a 400 error stating these headers are required, you can disable this validation.

Environment Variable: Helldivers__API__ValidateClients (set to false to disable).

JSON Config:

{
  "Helldivers": {
    "API": {
      "ValidateClients": false
    }
  }
}