diff options
| -rw-r--r-- | docs/technical-docs.md | 107 | ||||
| -rw-r--r-- | src/SMAPI.sln | 3 |
2 files changed, 99 insertions, 11 deletions
diff --git a/docs/technical-docs.md b/docs/technical-docs.md index d37d327d..37ec7f69 100644 --- a/docs/technical-docs.md +++ b/docs/technical-docs.md @@ -3,16 +3,25 @@ This file provides more technical documentation about SMAPI. If you only want to use or create mods, this section isn't relevant to you; see the main README to use or create mods. -## Contents -* [Development](#development) - * [Compiling from source](#compiling-from-source) - * [Debugging a local build](#debugging-a-local-build) - * [Preparing a release](#preparing-a-release) -* [Customisation](#customisation) - * [Configuration file](#configuration-file) - * [Command-line arguments](#command-line-arguments) - * [Compile flags](#compile-flags) - +# Contents +* [SMAPI](#smapi) + * [Development](#development) + * [Compiling from source](#compiling-from-source) + * [Debugging a local build](#debugging-a-local-build) + * [Preparing a release](#preparing-a-release) + * [Customisation](#customisation) + * [Configuration file](#configuration-file) + * [Command-line arguments](#command-line-arguments) + * [Compile flags](#compile-flags) +* [SMAPI web services](#smapi-web-services) + * [Overview](#overview) + * [Log parser](#log-parser) + * [Mods API](#mods-api) + * [Development](#development-2) + * [Local development](#local-development) + * [Deploying to Amazon Beanstalk](#deploying-to-amazon-beanstalk) + +# SMAPI ## Development ### Compiling from source Using an official SMAPI release is recommended for most users. @@ -135,3 +144,81 @@ SMAPI uses a small number of conditional compilation constants, which you can se flag | purpose ---- | ------- `SMAPI_FOR_WINDOWS` | Indicates that SMAPI is being compiled on Windows for players on Windows. Set automatically in `crossplatform.targets`. + + +# SMAPI web services +## Overview +The `StardewModdingAPI.Web` project provides an API and web UI hosted at `*.smapi.io`. + +### Log parser +The log parser provides a web UI for uploading, parsing, and sharing SMAPI logs. The logs are +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; it doesn't do anything currently, but lets us version breaking changes if needed. + +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 accepts either `GET` or `POST` for convenience: +> ``` +>GET https://api.smapi.io/v2.0/mods?modKeys=nexus:541,chucklefish:4228 +>``` + +>``` +>POST https://api.smapi.io/v2.0/mods +>{ +> "ModKeys": [ "nexus:541", "chucklefish:4228" ] +>} +>``` + +It returns a response like this: +>``` +>{ +> "chucklefish:4228": { +> "name": "Entoarox Framework", +> "version": "1.8.0", +> "url": "https://community.playstarbound.com/resources/4228" +> }, +> "nexus:541": { +> "name": "Lookup Anything", +> "version": "1.16", +> "url": "http://www.nexusmods.com/stardewvalley/mods/541" +> } +>} +>``` + +## Development +### Local development +`StardewModdingAPI.Web` is a regular ASP.NET MVC Core app, so you can just launch it from within +Visual Studio to run a local version. + +There are two differences when it's run locally: all endpoints use HTTP instead of HTTPS, and the +subdomain portion becomes a route (e.g. `log.smapi.io` → `localhost:59482/log`). + +Before running it locally, you need to enter your credentials in the `appsettings.Development.json` +file. See the next section for a description of each setting. This file is listed in `.gitignore` +to prevent accidentally committing credentials. + +### Deploying to Amazon Beanstalk +The app can be deployed to a standard Amazon Beanstalk IIS environment. When creating the +environment, make sure to specify the following environment properties: + +property name | description +------------------------------- | ----------------- +`LogParser:PastebinDevKey` | The [Pastebin developer key](https://pastebin.com/api#1) used to authenticate with the Pastebin API. +`LogParser:PastebinUserKey` | The [Pastebin user key](https://pastebin.com/api#8) used to authenticate with the Pastebin API. Can be left blank to post anonymously. +`LogParser:SectionUrl` | The root URL of the log page, like `https://log.smapi.io/`. +`ModUpdateCheck:GitHubPassword` | The password with which to authenticate to GitHub when fetching release info. +`ModUpdateCheck:GitHubUsername` | The username with which to authenticate to GitHub when fetching release info. diff --git a/src/SMAPI.sln b/src/SMAPI.sln index 8d730f37..1cb858bc 100644 --- a/src/SMAPI.sln +++ b/src/SMAPI.sln @@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio 15 VisualStudioVersion = 15.0.27004.2002 MinimumVisualStudioVersion = 10.0.40219.1 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ConsoleCommands", "SMAPI.Mods.ConsoleCommands\StardewModdingAPI.Mods.ConsoleCommands.csproj", "{28480467-1A48-46A7-99F8-236D95225359}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StardewModdingAPI.Mods.ConsoleCommands", "SMAPI.Mods.ConsoleCommands\StardewModdingAPI.Mods.ConsoleCommands.csproj", "{28480467-1A48-46A7-99F8-236D95225359}" EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StardewModdingAPI", "SMAPI\StardewModdingAPI.csproj", "{F1A573B0-F436-472C-AE29-0B91EA6B9F8F}" EndProject @@ -37,6 +37,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{EB35A917-6 ..\docs\mod-build-config.md = ..\docs\mod-build-config.md ..\docs\README.md = ..\docs\README.md ..\docs\release-notes.md = ..\docs\release-notes.md + ..\docs\technical-docs.md = ..\docs\technical-docs.md EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{09CF91E5-5BAB-4650-A200-E5EA9A633046}" |