vsmoddb

Repository for https://mods.vintagestory.at

VS Mod DB API Docs

Format

Request: Normal GET requests

Response: Json. Every response contains a statuscode property which uses HTTP Error Codes to denote success/failure of a request.

URLS

Api base url http://mods.vintagestory.at/api

Api v2 base url - currently still in development http://mods.vintagestory.at/api/v2

Base url for all returned files http://mods.vintagestory.at/ Always respect the full uris returned by the api.

Interfaces

V1

/api/tags

List all mod tags

Example: http://mods.vintagestory.at/api/tags

/api/gameversions

List all game version tags

Example: http://mods.vintagestory.at/api/gameversions

/api/authors

List all authors (users)

Example: http://mods.vintagestory.at/api/authors

/api/comments/[assetid]

Lists all comments for given assetid or latest 100 if assetid is not specified

Example: http://mods.vintagestory.at/api/comments

/api/mods

List all mods

Example: http://mods.vintagestory.at/api/mods

Get Parameters:
tagids[]: Filter by tag id (AND)
gameversion or gv: Filter by game version id
gameversions[]: Filter by game version ids (OR)
author: Filter by author id
text: Search by mod text and title
orderby: Order by, one of: 'asset.created', 'lastreleased', 'downloads', 'follows', 'comments', 'trendingpoints' (default: asset.created)
orderdirection: Order direction, one of: 'desc', 'asc' (default: desc)

Search Example: http://mods.vintagestory.at/api/mods?text=jack&tagids[]=7&tagids[]=8&orderby=downloads

/api/mod/[modid]

List all info for given mod. Modid can be either the numbered id as retrieved by the mod list interface or the modid string from the modinfo.json

Example: http://mods.vintagestory.at/api/mod/6
String example: http://mods.vintagestory.at/api/mod/carrycapacity

V2 - still under development

/api/v2/users/by-name/{search}

• get:
  • Args:
    • Path arg {search}
    • limit: Optional result count limit between 1 and 200 inclusive. Defaults to 10.
    • contributors-only: Optional filter to only return users that have contributed to at least one mod.
  • 200: string - string dictionary, where keys are user hashes and values are usernames.

Important

Endpoints marked as auth require authentication and response with 401 if it is missing.
Endpoints marked as at additionally require a valid actiontoken and response with 400 if it is missing. The token can be provided as a query parameter or in the POST body.

/api/v2/mods/install-information

• get:
  • Args:
    • Query arg ids: Comma separated list of {identifier}@{version} pairs, where {identifier} is the identifier specified in the modinfo, and {version} is the semvar string of the desired version. If a gv is specified, the @{version} segment becomes optional.
    • Optional query arg gv: semvar string of the target game version
    • Optional query arg ignore-retraction: truthy value indicating that retracted releases should return their attachment anyways.
    • Optional query arg hosted-mode: truthy value indicating that the game is running in hosted mode, and only special mods are allowed.
  • 400: Malformed game version, no ids or all ids are malformed.
  • 200: json of the following format is returned:

     {
     	"data": {
     		"modidentifier": {
     			"errorCode": 1234,
     		},
     		"modidentifier2": {
     			"fileName": "file.zip",
     			"fileUrl": "/download/12331/file.zip"
     		},
     		"modidentifier3": {
     			"fileName": "file.zip",
     			"fileUrl": "/download/12332/file.zip",
     			"recommendedUpgrade": "2.3.4"
     		},
     		"modidentifier5": {
     			"errorCode": 4101,
     			"retractionReason": "The reason why this release was retracted",
     			"recommendedUpgrade": "2.3.4"
     		},
     		...
     	}
     }

    • recommendedUpgrade is provided if
      • a) no version was provided as part of the mod spec -> this is the selected version
      • b) a gameversion was specified, and there is a newer version of the mod than specified that is compatible with that game version. The other data still pertains to the version of the mod spec.
    • Without the ignore-retraction argument specified, retracted releases will not respond with fileName and fileUrl.
    • errorCode is a numeric code similar to http status codes indicating the error in a machine readable format:
      • 4001: Failed to parse mod spec
      • 4002: Mod spec does not contain a version and no gameversion was provided.
      • 4031: Mod not allowed in hosted mode
      • 4032: Cannot ignore release retraction
      • 4031: Mod spec not found
      • 4101: Release is retracted
      • 4102: Release is force-retracted (cannot be ignored)

/api/v2/mods/{modid}/releases

• get: Path arg {modid}
  • 400: Not implemented

/api/v2/mods/{modid}/releases/all

• get: Path arg {modid}
  • 400: Not implemented

/api/v2/mods/{modid}/releases/{releaseid}

• get
  • Args:
    • Path arg {modid}
    • Path arg {releaseid}
  • 400: Not implemented
• post auth at
  • Args:
    • Path arg {modid}
    • Path arg {releaseid}
  • 400: Not implemented

/api/v2/mods/{modid}/releases/new auth at

• put: Path arg {modid}
  • 400: Not implemented

/api/v2/mods/{modid}/releases/{releaseid}/retraction auth at

• put:
  • Args:
    • Path arg {modid}
    • Path arg {releaseid}
  • 400: Invalid action token.
  • 400: Missing reason.
  • 400: Release is already retracted.
  • 400: Mod / release mismatch.
  • 403: User does not have permission to edit release.
  • 404: Target release does not exist.
  • 200: Successfully retracted the release.

/api/v2/mods/{modid}/releases/upload-limit auth at

• get:
  • Args:
    • Path arg {modid}
  • 400: Invalid action token.
  • 404: Target mod does not exist.
  • 200: Returns numeric limit or empty if there isn't one besides the default.
• put:
  • Args:
    • Path arg {modid}
    • Post arg limit: Numeric limit or empty to indicate a reset to default.
  • 400: Invalid action token or malformed request.
  • 404: Target mod does not exist.
  • 200: Limit was successfully updated.

/api/v2/mods/{modid}/comments

• get: Path arg {modid}
  • 404: Not implemented.
• put: auth at
  • Args:
    • Path arg {modid}
    • Request body: Desired comment html.
  • 400: Invalid action token or malformed request.
  • 404: Target mod does not exist.
  • 403: Active user is currently restricted.
  • 200: Comment got created. Returns the processed html of the newly created comment as the response body, and the link to the comment in the Location header.

/api/v2/mods/{modid}/lock auth at

• post:
  • Args:
    • Path arg {modid}
  • 400: Invalid action token or malformed request.
  • 404: Target mod does not exist.
  • 403: The authenticated user is not allowed to lock mods, or is currently restricted.
  • 200: Mod was successfully locked.

/api/v2/comments/{commentid} auth at

• post:

  • Args:
    • Path arg {commentid}
    • Request body: Desired comment html.
  • 400: Invalid action token or malformed request.
  • 404: Target comment does not exist.
  • 403: Active user is currently restricted or does not have permissions to edit the comment.
  • 200: Comment got updated. Returns the processed comment html as a object {html: string}.

• delete: Path arg {commentid}

  • 400: Invalid action token or malformed request.
  • 404: Target comment does not exist.
  • 403: Active user is currently restricted or does not have permissions to delete the comment.
  • 200: Comment got deleted.

/api/v2/notifications auth

• get: No args.
  • 200: Array of notification ids for the current user. May be empty.

/api/v2/notifications/{id} auth

• get: Path arg {id}
  • 404: Not implemented.

/api/v2/notifications/all auth

• get: No args.
  • 404: Not implemented.

/api/v2/notifications/clear auth

• post:
  • Args:
    • ids: Comma separated list of integers (takes priority). or
    • ids[]: formurlencoded ids.
  • 400: No ids provided or argument malformed.
  • 403: List of ids contains notifications that do not belong to the current user.
  • 200: Notifications were marked as read if they exist.

/api/v2/notifications/settings/followed-mods/{id} auth

• post:
  • Args:
    • Path arg {id} specifies the target mod id. Specifying an id that is not already followed will follow that mod with specified settings.
    • new: Integer value specifying the new settings.
      • 1 << 0: Should receive notifications when this mod is updated.
  • 400: No new value provided or argument is malformed.
  • 200: Successfully updated settings.

/api/v2/notifications/settings/followed-mods/{id}/unfollow auth

• post: Path arg {id} specifies the target mod id.
  • 400: Argument is malformed.
  • 200: Successfully unfollowed if mod was followed.

/api/v2/game-versions

• get: (currently also auth TODO(Rennorb) @bug)
  • 200: Returns string array of available game-versions in descending order.
• post: auth at
  • Args:
    • new specifies the new version to add. Must parse as our semver derivate.
  • 400: Argument is malformed.
  • 403: Active user is currently restricted or does not have permissions to add a new game-version.
  • 409: The version to be added already exists.
  • 201: Successfully added the new game-version.

/api/v2/game-versions/{version}

• delete: auth at
  • Args:
    • Path arg {version} specifies the game-version to delete. Must parse as our semver derivate.
  • 400: Argument is malformed or missing.
  • 403: Active user is currently restricted or does not have permissions to delete the game-version.
  • 404: The specified version does not exist.
  • 200: Successfully deleted the specified game-version.

Development setup

VS Code - Remote Containers (untested for a while now)

You can use the provided vscode devcontainer to get up a running without installing everything on your own.

Required for that is docker installed aswell as docker-compose and vscode with the Remote-Containers extension. Then you can open the devcontainer.json in vscode, and it should prompt you

Folder contains a Dev Container configuration file. Reopen folder to develop in a container ([learn more](https://aka.ms/vscode-remote/docker)).

Simply click reopen in container, and it should start building the devcontainer and starting the mysql database aswell.

Now edit the config.php to match the settings in the dockerdocker-compose.yml for the db MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD and add 127.0.0.1 mods.vintagestory.stage to your hosts file on your local machine.

To deploy the database to the mysql instance run the tables.sql script against the database. You can use MySQL WOrkbench or any other mysql tool. When connecting from your local machine use localhost and 3306 (default) port to connect.

There is also a optional MySQL Workbench container that when enabled in the dockerdocker-compose.yml can be reached at http://localhost:4444/. To connect to the mysql database from workbench container use db for the hostname.

Universal (vscode/intellij/notepad)

Requirements:

• Docker

Steps:

• add 127.0.0.1 mods.vintagestory.stage to your hosts file (this has to be a different domain from vintagestory.at, because that domain uses HSTS and so a self signed cert will not be deemed acceptable by browsers)
• run docker compose up -d inside docker/
• edit config.php to match the settings in dockerdocker-compose.yml

Result:

• https://mods.vintagestory.stage/
  • Since we are using ssl now you will need to add an exception for https://mods.vintagestory.stage to your browser to view the page.
• Adminer instance
• mysql 3306 is exposed

Note: the mysql container is set up to automatically execute the provided DB structure + sample data.

Note: in staging environments you can append ?showas=<id> to any url to load the page the user with that id. This can be used debugging and testing role related features.

Compiling styles

We are now using Sass, mostly just to combine multiple stylesheets into one and minify them.

You can either download the standalone version of sass for your os, or install it globally into the node package manager via npm install -g sass.

To compile the styles into one file run the command for your method of installation:

• standalone: sass --style=compressed --update web/_sass/_style.scss:web/css/style.css
• npm: npx sass --style=compressed --update web/_sass/_style.scss:web/css/style.css (simply prepend npx)

If you add the -w argument to this command, sass will continue running after the first compile instead of terminating, and watch for changes to the soruce files, which will trigger a automatic recompile.

Compiling scripts

We are now using typescript in combination with rollup, mostly just to combine multiple scripts into one and minify them.

Both of these want to be installed globally into the node package manager via npm install -g typescript terser.

To only compile typescript without compression the following command can be used: npx tsc --target ES2021 --module none --removeComments --allowJs --alwaysStrict --outFile tmp/script.js --inlineSourceMap web/_ts/_script.ts
To properly compress the output terser is used roughly as follows npx terser tmp/script.js -c 'passes=3,keep_fargs=false' -m -o web/js/script.js --source-map "url='script.js.map',content='inline'".

We purposefully do not include any configuration files for sass or tsc in the repository for now to avoid any unnecessary tool bloat.

Testing

I've recently started adding tests for some components of the ModDB. For now they are based on php unit and require quite specific arguments to run.

If you have php installed globally

If you have a global php installation (with Phar handling) and of the correct version (7.4), you can use it to run the tests:

1. cd tests
2. php phpunit.phar --test-suffix=.php .

Using the provided docker container

If you don't have php installed you can still use hte container that already runs the local development version of ModDB:

1. docker compose -f docker/docker-compose.yml exec php php tests/phpunit.phar --test-suffix=.php tests

Both of the methods should yield the same result.