stefanidze/minecraft-api repository overview

⁠Minecraft Control API

This API is intended to bridge the gap between languages and RCON libraries, best used in a docker compose with your product of choice

⁠Setup

• The API takes in a config.toml file as a docker compose secret Path to this file is controlled by CONFIG_FILE_PATH env
• Config file has the following structure:

    token = "wawa"

    use_encryption = true
    use_rotation = true
    use_https = true

    expose_tests_endpoint = true

    [server_config]
      adress = "127.0.0.1"
      port = 102345
      password = "wawacat"

• Where:
  • token - a secret between API and your app, which is required to submit any request. Can be any string value you want (use a password generator)
  • use_encryption - tells the app whether the token is encrypted with the minecraft server password. Because the API works over http this is highly recommended to avoid the risks of token being exposed over plain http. Expects an encrypted value hexidecimal string as token if enabled. You can use /testing/ endpoints to test various encryption logic
  • use_rotation - tells the app weather the token IV should be rotated. You will need custom encryption logic to keep encrypting the token with the IV supplied in the responce. The same IV will be used for decryption.
  • use_https - enables the app to use HTTPS using Kestrel configuration supplied from docker compose. If this option is checked the app will only listen on HTTPS.
  • expose_tests_endpoint - If unchecked disables /testing endpoint and causes all the requests to that endpoint return 501 withour further processing
  • server_config - a place for your rcon credentials. The password from here is used for token decryption.

⁠Spec

Swagger is active at /swagger/index.html, check return types there.

Token is passed as a token header

⁠Main Endpoint

⁠/main/command

• POST Request
• Requres a valid token
• Accepts a command payload as a JSON string as body
• Assumes command failure as Bad Request
• Returns command responce and ID

⁠/main/connection/init

• POST Request
• Requres a valid IV for the next token is rotation is enabled
• Creates a client and esteablishes a connection with a minecraft server
• Returns 404 if server did not respond and 401 if password was incorrect

⁠/main/connection/heathcheck

• GET Request
• Requres a valid token
• Runs a pre-defined "seed" command
• Assumes command failure as Internal Server Error
• Returns command responce and ID
• Returns 503 if client not connected
• Is a way to check if connection has been esteablished

⁠/main/connection/close

• POST Request
• Requres a valid token
• Closes a connetion between the API and the minecraft server
• Returns token rotation into initial state

⁠Testing Endpoint

⁠/testing/encrypt

• POST Request
• Encrypts a value (body) with a key (header) and a 16-bit hexidecimal IV (header)
• Returns a hexidecimal string of encrypted data

⁠/testing/decrypt

• POST Request
• Decrypts a value (body) with a key (header) and a 16-bit hexidecimal IV (header)
• Returns a string of decrypted data

⁠/testing/rotation/decrypt

• POST Request
• Decrypts a value (body) with a key (header) and a current in-memory IV
• Rotates the IV once and returns the IV that is expected to be used for encrypting data next time.

⁠/testing/rotation/IV

• GET Request
• Returns the current IV used for test rotation (not the real one) as a hexidecimal string

⁠/testing/rotation/reset

• POST Request
• Resets the testing IV to an empty array of 16 bytes
• Returns nothing

⁠Important

This image is a part of a bigger project and it will not run correctly without accompanying docker-compose.yml file. All the needed resources can be found at the project gitlab⁠