Skip to content

WebApi.md

Latest commit

 

History

History
239 lines (125 loc) · 4.34 KB

WebApi.md

File metadata and controls

239 lines (125 loc) · 4.34 KB

Web API

MHServerEmu can provide web API functionality as part of its web frontend. It is enabled by default, and the server listens for requests on http://localhost:8080/. This can be customized in the WebFrontend section of Config.ini.

The web API uses JSON for serialization. Requests return JSON as output and expect JSON as input in the request's body when needed.

Some endpoints are restricted and require an API key to access.

  • API keys can be generated using the !webapi generatekey command.

  • API keys are saved to Data/Web/ApiKeys.json. Keys can be reloaded from this file at runtime using the !webapi reloadkeys command.

  • API keys are not logged, the only way to access generated keys is by reading them from the ApiKeys.json file.

  • Each API key has a specific access type assigned to it (e.g. AccountManagement), which limits its functionality to a specific domain.

  • API keys need to be provided when making requests to restricted endpoints by adding them as an Authorization HTTP request header with the Bearer scheme (e.g. Authorization: Bearer FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF).

Below is reference information on available endpoints.

Account Management

/AccountManagement/Create

POST

Requests the server to create an account with the provided data.

  • Access: None

  • Input Fields:

    • string Email

    • string PlayerName

    • string Password

  • Output Fields:

    • int Result

/AccountManagement/SetPlayerName

POST

Requests the server to change the player name of an existing account.

  • Access: AccountManagement

  • Input Fields:

    • string Email

    • string PlayerName

  • Output Fields:

    • int Result

/AccountManagement/SetPassword

POST

Requests the server to change the password of an existing account.

  • Access: AccountManagement

  • Input Fields:

    • string Email

    • string Password

  • Output Fields:

    • int Result

/AccountManagement/SetUserLevel

POST

Requests the server to change the user level of an existing account.

  • Access: AccountManagement

  • Input Fields:

    • string Email

    • byte UserLevel

  • Output Fields:

    • int Result

/AccountManagement/SetFlag

POST

Requests the server to set a flag on an existing account.

  • Access: AccountManagement

  • Input Fields:

    • string Email

    • int Flags

  • Output Fields:

    • int Result

Account Flag Reference:

enum AccountFlags
{
    None                                = 0,
    IsBanned                            = 1 << 0,
    IsArchived                          = 1 << 1,
    IsPasswordExpired                   = 1 << 2,
    DEPRECATEDLinuxCompatibilityMode    = 1 << 3,
    IsWhitelisted                       = 1 << 4,
}

/AccountManagement/ClearFlag

POST

Requests the server to clear a flag on an existing account.

  • Access: AccountManagement

  • Input Fields:

    • string Email

    • int Flags

  • Output Fields:

    • int Result

See /AccountManagement/SetFlag above for flag reference.

Server Status

/ServerStatus

GET

Retrieves server status information.

  • Access: None

  • Output:

    • Dictionary<string, long>

Region Report

/RegionReport

GET

Retrieves server region information.

  • Access: None

  • Output Fields:

    • List<RegionReport.Entry> Regions

      • string GameId

      • string RegionId

      • string Name

      • string DifficultyTier

      • string Uptime

Metrics

/Metrics/Performance

GET

Retrieves server performance metrics.

  • Access: None

  • Output Fields:

    • string Id

    • MemoryMetrics.Report Memory

      • long GCIndex

      • long GCCountGen0

      • long GCCountGen1

      • long TotalCommittedBytes

      • long HeapSizeBytes

      • double PauseTimePercentage

      • MetricTracker.ReportEntry PauseDuration

    • Dictionary<ulong, GamePerformanceMetrics.Report> Games

      • MetricTracker.ReportEntry UpdateTime

      • MetricTracker.ReportEntry FrameTime

      • MetricTracker.ReportEntry ScheduledEventsPerUpdate

      • MetricTracker.ReportEntry EntityCount

      • MetricTracker.ReportEntry PlayerCount

  • MetricTracker.ReportEntry fields:

    • float Average

    • float Median

    • float Last

    • float Min

    • float Max