diff --git a/docs/Index.md b/docs/Index.md index d93ad4de..7f798f3e 100644 --- a/docs/Index.md +++ b/docs/Index.md @@ -17,6 +17,7 @@ If this is your first time using MHServerEmu, you may be interested in this. MHServerEmu-specific topics. - [Server Commands](./ServerEmu/ServerCommands.md) - a list of available server commands. +- [Web API](./ServerEmu/WebApi.md) - web API documentation. ## Game diff --git a/docs/ServerEmu/WebApi.md b/docs/ServerEmu/WebApi.md new file mode 100644 index 00000000..33263a5b --- /dev/null +++ b/docs/ServerEmu/WebApi.md @@ -0,0 +1,239 @@ +# 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: + +```csharp +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` + +## Region Report + +### /RegionReport + +#### GET + +Retrieves server region information. + +- Access: `None` + +- Output Fields: + + - `List 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 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`