← README
SMAPI.Web contains the code for the smapi.io website, including the mod compatibility list
and update check API.
The log parser at https://smapi.io/log provides a web UI for uploading, parsing, and sharing SMAPI logs.
The logs are saved in a compressed form to Amazon Blob storage for 30 days.
The JSON validator at https://smapi.io/json provides a web UI for uploading and sharing JSON files,
and validating them as plain JSON or against a predefined format like manifest.json or Content
Patcher's content.json.
The logs are saved in a compressed form to Amazon Blob storage for 30 days.
Schema files are defined in wwwroot/schemas using the JSON Schema
format. The JSON validator UI recognises a superset of the standard fields to change output:
- Documentation URL
-
The root schema may have a
@documentationURLfield, which is a web URL for the user documentation:"@documentationUrl": "https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest"
If present, this is shown in the JSON validator UI.
- Error messages
-
Any part of the schema can define an
@errorMessagesfield, which overrides matching schema errors. You can override by error code (recommended), or by error type and a regex pattern matched against the error message (more fragile):// by error type "pattern": "^[a-zA-Z0-9_.-]+\\.dll$", "@errorMessages": { "pattern": "Invalid value; must be a filename ending with .dll." }
// by error type + message pattern "@errorMessages": { "oneOf:valid against no schemas": "Missing required field: EntryDll or ContentPackFor.", "oneOf:valid against more than one schema": "Can't specify both EntryDll or ContentPackFor, they're mutually exclusive." }
Error messages may contain special tokens:
-
The
@valuetoken is replaced with the error's value field. This is usually (but not always) the original field value. -
When an error has child errors, by default they're flattened into one message:
line | field | error ---- | ---------- | ------------------------------------------------------------------------- 4 | Changes[0] | JSON does not match schema from 'then'. | | ==> Changes[0].ToArea.Y: Invalid type. Expected Integer but got String. | | ==> Changes[0].ToArea: Missing required fields: Height.If you set the message for an error to
$transparent, the parent error is omitted entirely and the child errors are shown instead:line | field | error ---- | ------------------- | ---------------------------------------------- 8 | Changes[0].ToArea.Y | Invalid type. Expected Integer but got String. 8 | Changes[0].ToArea | Missing required fields: Height.The child errors themselves may be marked
$transparent, etc. If an error has no child errors, this override is ignored.Validation errors for
thenblocks are transparent by default, unless overridden.
-
You can reference the validator schemas in your JSON file directly using the $schema field, for
text editors that support schema validation. For example:
{
"$schema": "https://smapi.io/schemas/manifest.json",
"Name": "Some mod",
...
}Available schemas:
SMAPI provides a web API at smapi.io/api for use by SMAPI and external tools. The URL includes a
{version} token, which is the SMAPI version for backwards compatibility. This API is publicly
accessible but not officially released; it may change at any time.
The API has one /mods endpoint. This crossreferences the mod against a variety of sources (e.g.
the wiki, Chucklefish, CurseForge, ModDrop, and Nexus) to provide metadata mainly intended for
update checks.
The API accepts a POST request with these fields:
| field | summary | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
mods |
The mods for which to fetch metadata. Included fields:
|
||||||||||
apiVersion |
(optional) The installed version of SMAPI. If not specified, the API won't recommend an update. |
||||||||||
gameVersion |
(optional) The installed version of Stardew Valley. This may be used to select updates. |
||||||||||
platform |
(optional) The player's OS ( |
||||||||||
includeExtendedMetadata |
(optional) Whether to include extra metadata that's not needed for SMAPI update checks, but which may be useful to external tools. |
Example request:
POST https://smapi.io/api/v4.0.0/mods
{
"mods": [
{
"id": "Pathoschild.ContentPatcher",
"updateKeys": [ "nexus:1915" ],
"installedVersion": "1.9.2",
"isBroken": false
}
],
"apiVersion": "4.0.0",
"gameVersion": "1.6.9",
"platform": "Windows",
"includeExtendedMetadata": true
}Response fields:
| field | summary | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id |
The mod ID you specified in the request. |
||||||||||||||||||||||||||||||||
suggestedUpdate |
The update version recommended by the web API, if any. This is based on some internal rules (e.g.
it won't recommend a prerelease update if the player has a working stable version). Choosing an
update version yourself isn't recommended, but you can set |
||||||||||||||||||||||||||||||||
errors |
Human-readable errors that occurred fetching the version info (e.g. if a mod page has an invalid version). |
||||||||||||||||||||||||||||||||
metadata |
Extra metadata that's not needed for SMAPI update checks but which may be useful to external tools,
if you set
|
Example response with includeExtendedMetadata: false:
[
{
"id": "Pathoschild.ContentPatcher",
"suggestedUpdate": {
"version": "1.10.0",
"url": "https://www.nexusmods.com/stardewvalley/mods/1915"
},
"errors": []
}
]Example response with includeExtendedMetadata: true:
[
{
"id": "Pathoschild.ContentPatcher",
"suggestedUpdate": {
"version": "1.10.0",
"url": "https://www.nexusmods.com/stardewvalley/mods/1915"
},
"metadata": {
"id": [ "Pathoschild.ContentPatcher" ],
"name": "Content Patcher",
"nexusID": 1915,
"curseForgeID": 309243,
"modDropID": 470174,
"gitHubRepo": "Pathoschild/StardewMods",
"main": {
"version": "1.10",
"url": "https://www.nexusmods.com/stardewvalley/mods/1915"
},
"compatibilityStatus": "Ok",
"compatibilitySummary": "✓ use latest version."
},
"errors": []
}
]The /mods/metrics endpoint returns a summary of update-check metrics since the server was last
deployed or restarted.
Example request:
GET https://smapi.io/api/v4.0.0/mods/metricsThe SMAPI web services provides a few short URLs for convenience:
A local environment lets you run a complete copy of the web project (including cache database) on your machine, with no external dependencies aside from the actual mod sites.
-
Edit
appsettings.Development.jsonand set these options:property name description NexusApiKeyYour Nexus API key. Optional settings:
property name description AzureBlobConnectionStringThe connection string for the Azure Blob storage account. Defaults to using the system's temporary file folder if not specified. GitHubUsernameGitHubPasswordThe GitHub credentials with which to query GitHub release info. Defaults to anonymous requests if not specified. -
Launch
SMAPI.Webfrom Visual Studio to run a local version of the site.
A production environment includes the web servers and cache database hosted online for public access.
This section assumes you're creating a new environment on Azure, but the app isn't tied to any Azure services. If you want to host it on a different site, you'll need to adjust the instructions accordingly.
Initial setup:
-
Create an Azure Blob storage account for uploaded files.
-
Create an Azure App Services environment running the latest .NET on Linux or Windows.
-
Add these application settings in the new App Services environment:
property name description ApiClients.AzureBlobConnectionStringThe connection string for the Azure Blob storage account created in step 2. ApiClients.GitHubUsernameApiClients.GitHubPasswordThe login credentials for the GitHub account with which to fetch release info. If these are omitted, GitHub will impose much stricter rate limits. ApiClients:NexusApiKeyThe Nexus API authentication key. Optional settings:
property name description BackgroundServices:EnabledSet to trueto enable background processes like fetching data from the wiki, or false to disable them.Site:OtherBlurbA message to show below the download button (e.g. for details on downloading a beta version), in Markdown format. Site:SupporterListA list of Patreon supports to credit on the download page.
To deploy updates, just redeploy the web project from Visual Studio.