From 4dbbe363231600075ab76bf0ccbab92ddc7b841b Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Fri, 29 Jun 2018 01:27:48 -0400
Subject: [PATCH] update technical docs for web API (#532)

---
 docs/technical-docs.md | 97 ++++++++++++++++++++++++------------------
 1 file changed, 55 insertions(+), 42 deletions(-)

diff --git a/docs/technical-docs.md b/docs/technical-docs.md
index bdb731d1..d829baf9 100644
--- a/docs/technical-docs.md
+++ b/docs/technical-docs.md
@@ -158,53 +158,66 @@ persisted in a compressed form to Pastebin.
 
 The log parser lives at https://log.smapi.io.
 
-### Mods API
-The mods API provides version info for mods hosted by Chucklefish, GitHub, or Nexus Mods. It's used
-by SMAPI to perform update checks. The `{version}` URL token is the version of SMAPI making the
-request, and is used when needed for backwards compatibility.
-
-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.
+### Web API
+SMAPI provides a web API at `api.smapi.io` 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 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
-update keys.
->```
->POST https://api.smapi.io/v2.0/mods
->{
->   "mods": [
->      {
->         "id": "Pathoschild.LookupAnything",
->         "updateKeys": [ "nexus:541", "chucklefish:4250" ]
->      }
->   ]
->}
->```
+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
+the given ID.
 
-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
-newer, the latest optional version will be shown as the 'preview version'.
->```
->{
->   "Pathoschild.LookupAnything": {
->      "id": "Pathoschild.LookupAnything",
->      "name": "Lookup Anything",
->      "version": "1.18",
->      "url": "https://www.nexusmods.com/stardewvalley/mods/541",
->      "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 '*'."
->      ]
->   }
+```
+POST https://api.smapi.io/v2.0/mods
+{
+   "mods": [
+      {
+         "id": "Pathoschild.LookupAnything",
+         "updateKeys": [ "nexus:541", "chucklefish:4250" ]
+      }
+   ],
+   "includeExtendedMetadata": true
 }
->```
+```
+
+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
 ### Local development