StardewValley
/
SMAPI
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update technical docs for web API (#532)

This commit is contained in:
Jesse Plamondon-Willard 2018-06-29 01:27:48 -04:00
parent 60b38666e2
commit 4dbbe36323
1 changed files with 55 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/technical-docs.md
View File

@ -158,53 +158,66 @@ persisted in a compressed form to Pastebin.
The log parser lives at https://log.smapi.io. The log parser lives at https://log.smapi.io.
### Mods API ### Web API
The mods API provides version info for mods hosted by Chucklefish, GitHub, or Nexus Mods. It's used SMAPI provides a web API at `api.smapi.io` for use by SMAPI and external tools. The URL includes a
by SMAPI to perform update checks. The `{version}` URL token is the version of SMAPI making the `{version}` token, which is the SMAPI version for backwards compatibility. This API is publicly
request, and is used when needed for backwards compatibility. accessible but not officially released; it may change at any time.
Each mod is identified by a repository key and unique identifier (like `nexus:541`). The following
repositories are supported:
key | repository
------------- | ----------
`chucklefish` | A mod page on the [Chucklefish mod site](https://community.playstarbound.com/resources/categories/22), identified by the mod ID in the page URL.
`github` | A repository on [GitHub](https://github.com), identified by its owner and repository name (like `Zoryn4163/SMAPI-Mods`). This checks the version of the latest repository release.
`nexus` | A mod page on [Nexus Mods](https://www.nexusmods.com/stardewvalley), identified by the mod ID in the page URL.
The API has one `/mods` endpoint. This provides mod info, including official versions and URLs
(from Chucklefish, GitHub, or Nexus), unofficial versions from the wiki, and optional mod metadata
from the wiki and SMAPI's internal data. This is used by SMAPI to perform update checks, and by
external tools to fetch mod data.
The API accepts a `POST` request with the mods to match, each of which **must** specify an ID and The API accepts a `POST` request with the mods to match, each of which **must** specify an ID and
update keys. may _optionally_ specify [update keys](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest#Update_checks).
>``` The API will automatically try to fetch known update keys from the wiki and internal data based on
>POST https://api.smapi.io/v2.0/mods the given ID.
>{
> "mods": [
> {
> "id": "Pathoschild.LookupAnything",
> "updateKeys": [ "nexus:541", "chucklefish:4250" ]
> }
> ]
>}
>```
The API will automatically aggregate versions and errors, and return a response like this. The ```
latest version is the main mod version (e.g. 'latest version' field on Nexus); if available and POST https://api.smapi.io/v2.0/mods
newer, the latest optional version will be shown as the 'preview version'. {
>``` "mods": [
>{ {
> "Pathoschild.LookupAnything": { "id": "Pathoschild.LookupAnything",
> "id": "Pathoschild.LookupAnything", "updateKeys": [ "nexus:541", "chucklefish:4250" ]
> "name": "Lookup Anything", }
> "version": "1.18", ],
> "url": "https://www.nexusmods.com/stardewvalley/mods/541", "includeExtendedMetadata": true
> "previewVersion": "1.19-beta",
> "previewUrl": "https://www.nexusmods.com/stardewvalley/mods/541",
> "errors": [
> "The update key 'chucklefish:4250' matches a mod with invalid semantic version '*'."
> ]
> }
} }
>``` ```
The API will automatically aggregate versions and errors. Each mod will include...
* an `id` (matching what you passed in);
* up to three versions: `main` (e.g. 'latest version' field on Nexus), `optional` if newer (e.g.
optional files on Nexus), and `unofficial` if newer (from the wiki);
* `metadata` with mod info crossreferenced from the wiki and internal data (only if you specified
`includeExtendedMetadata: true`);
* and `errors` containing any error messages that occurred while fetching data.
For example:
```
[
{
"id": "Pathoschild.LookupAnything",
"main": {
"version": "1.19",
"url": "https://www.nexusmods.com/stardewvalley/mods/541"
},
"metadata": {
"id": [
"Pathoschild.LookupAnything",
"LookupAnything"
],
"name": "Lookup Anything",
"nexusID": 541,
"gitHubRepo": "Pathoschild/StardewMods",
"compatibilityStatus": "Ok",
"compatibilitySummary": "✓ use latest version."
},
"errors": []
}
]
```
## Development ## Development
### Local development ### Local development