Download API: Difference between revisions
No edit summary |
mNo edit summary |
||
| (36 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
This API allows you to download official releases of stand-alone Factorio from the Factorio servers. It's not so much of an API as it is web scraping, but it's documented here for completeness. Please note that's there's a separate, (semi)official API for upgrading between releases, which should be used when possible to lighten load on the Factorio servers. (I'll document that later, promise!) | <div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Internal|Internal API]]</div> | ||
This API allows you to download official releases of stand-alone Factorio from the Factorio servers. It's not so much of an API as it is web scraping, but it's documented here for completeness. Please update this page if you utilize it and the information becomes outdated. Also note that's there's a separate, (semi)official API for upgrading between releases, which should be used when possible to lighten the load on the Factorio servers. (I'll document that later, promise!) | |||
== Authenticating == | == Authenticating == | ||
Downloading Factorio requires an authenticated session with the web server, which is different than the typical authentication mechanism. | Downloading Factorio requires an authenticated session with the web server, which is different than the typical API authentication mechanism. Authentication uses the HTML endpoint at | ||
<code>https://www.factorio.com/login</code> | |||
Login in procedure: | |||
# Create an HTTP session and send a GET request. You'll get some HTML in return.<br>There's a [[:Wikipedia:Cross-site_request_forgery#Synchronizer_token_pattern|CSRF token]] you'll need to grab which can be found using one of the following selectors: | |||
#* CSS1: <code>input[name=csrf_token]</code> (and then take the "value" attribute). | |||
#* XPATH1: <code>//input[@name="csrf_token"]/@value</code> | |||
# Then send a POST request with the following parameters: | |||
#* <code>csrf_token</code>: the CSRF token you grabbed earlier. | |||
#* <code>username_or_email</code>: your username or email address. | |||
#* <code>password</code>: your password. | |||
== Downloading == | |||
Download Factorio releases at | |||
<code>https://www.factorio.com/get-download/{version}/{build}/{distro}</code> | |||
* Where {version} is the version string of the release you wish to grab - e.g. "0.15.31". Use "latest" instead to default to the latest version for that build. | |||
* {build} is the release build, which currently comprises of: | |||
** <code>alpha</code> - the current standard full-featured build. | |||
** <code>demo</code> - the free, publicly accessible demo versions. | |||
** <code>headless</code> - for running servers on machines without graphical interface. | |||
* and {distro} is the os / type of release you wish to download, currently: | |||
** <code>win64</code> - EXE installer for 64 bit Windows. | |||
** <code>win64-manual</code> - ZIP package for 64 bit Windows. | |||
** <code>win32</code> - EXE installer for 32 bit Windows. ''No longer supported.'' | |||
** <code>win32-manual</code> - ZIP package for 32 bit Windows. ''No longer supported.'' | |||
** <code>osx</code> - DMG package for 64 bit Mac OS. | |||
** <code>linux64</code> - tar.gz or tar.xz package for 64 bit Linux. | |||
** <code>linux32</code> - tar.gz or tar.xz package for 32 bit Linux. ''No longer supported.'' | |||
Factorio servers will correctly respond with a 404 if the requested download isn't available. Experimental builds are taken down quickly after they become obsolete, so it's best to check what versions are available before hand (documented below). | |||
Note: Windows 32 bit and 64 bit installers are [https://en.wikipedia.org/wiki/Inno_Setup Inno Setup] formatted packages (I'll document that somewhere someday). | |||
== Version Listings == | |||
There is an API endpoint to find the latest version number at <code>https://factorio.com/api/latest-releases</code>. This can be polled to automatically detect when a new update was released. | |||
Due to changes in the Factorio website, all Factorio versions are now available on the HTML page at this location: | |||
<code>https://www.factorio.com/download/archive</code> | |||
Note: This endpoint require an authenticated session as mentioned above. | |||
You could the grab all the informations you need by parsing the HTML using selectors but I would recommend only searching for the pattern <code>href="/get-download/*"</code> and then parse the relative link according to the <code>/get-download/{version}/{build}/{distro}</code> structure described in the section above. The second method has a clear advantage of reliability through potential HTML structure changes and simplicity. | |||
It is also better to rely on the <code>https://factorio.com/api/latest-releases</code> endpoint and version number comparisons to distinguish between stable and experimental versions than to extract that information from the download HTML page with selectors. | |||
The previous endpoints for experimental and headless releases <code>https://www.factorio.com/download/experimental</code> and <code>https://www.factorio.com/download-headless</code> now both redirect to this page containing only the latest releases: | |||
<code>https://www.factorio.com/download</code> | |||
The selectors used to retrieve version numbers and build combinations are presented below, but they are probably obsolete. I will check them later and update this section accordingly. | |||
* CSS1: <code>h3</code> | |||
* XPATH1: <code>//h3</code> | |||
A list of available update packages is provided at <code>https://updater.factorio.com/get-available-versions</code>. | |||
{{Languages}}[[Category:Technical]] | {{Languages}}[[Category:Technical]] | ||
Latest revision as of 09:58, 25 February 2022
This API allows you to download official releases of stand-alone Factorio from the Factorio servers. It's not so much of an API as it is web scraping, but it's documented here for completeness. Please update this page if you utilize it and the information becomes outdated. Also note that's there's a separate, (semi)official API for upgrading between releases, which should be used when possible to lighten the load on the Factorio servers. (I'll document that later, promise!)
Authenticating
Downloading Factorio requires an authenticated session with the web server, which is different than the typical API authentication mechanism. Authentication uses the HTML endpoint at
https://www.factorio.com/login
Login in procedure:
- Create an HTTP session and send a GET request. You'll get some HTML in return.
There's a CSRF token you'll need to grab which can be found using one of the following selectors:- CSS1:
input[name=csrf_token](and then take the "value" attribute). - XPATH1:
//input[@name="csrf_token"]/@value
- CSS1:
- Then send a POST request with the following parameters:
csrf_token: the CSRF token you grabbed earlier.username_or_email: your username or email address.password: your password.
Downloading
Download Factorio releases at
https://www.factorio.com/get-download/{version}/{build}/{distro}
- Where {version} is the version string of the release you wish to grab - e.g. "0.15.31". Use "latest" instead to default to the latest version for that build.
- {build} is the release build, which currently comprises of:
alpha- the current standard full-featured build.demo- the free, publicly accessible demo versions.headless- for running servers on machines without graphical interface.
- and {distro} is the os / type of release you wish to download, currently:
win64- EXE installer for 64 bit Windows.win64-manual- ZIP package for 64 bit Windows.win32- EXE installer for 32 bit Windows. No longer supported.win32-manual- ZIP package for 32 bit Windows. No longer supported.osx- DMG package for 64 bit Mac OS.linux64- tar.gz or tar.xz package for 64 bit Linux.linux32- tar.gz or tar.xz package for 32 bit Linux. No longer supported.
Factorio servers will correctly respond with a 404 if the requested download isn't available. Experimental builds are taken down quickly after they become obsolete, so it's best to check what versions are available before hand (documented below).
Note: Windows 32 bit and 64 bit installers are Inno Setup formatted packages (I'll document that somewhere someday).
Version Listings
There is an API endpoint to find the latest version number at https://factorio.com/api/latest-releases. This can be polled to automatically detect when a new update was released.
Due to changes in the Factorio website, all Factorio versions are now available on the HTML page at this location:
https://www.factorio.com/download/archive
Note: This endpoint require an authenticated session as mentioned above.
You could the grab all the informations you need by parsing the HTML using selectors but I would recommend only searching for the pattern href="/get-download/*" and then parse the relative link according to the /get-download/{version}/{build}/{distro} structure described in the section above. The second method has a clear advantage of reliability through potential HTML structure changes and simplicity.
It is also better to rely on the https://factorio.com/api/latest-releases endpoint and version number comparisons to distinguish between stable and experimental versions than to extract that information from the download HTML page with selectors.
The previous endpoints for experimental and headless releases https://www.factorio.com/download/experimental and https://www.factorio.com/download-headless now both redirect to this page containing only the latest releases:
https://www.factorio.com/download
The selectors used to retrieve version numbers and build combinations are presented below, but they are probably obsolete. I will check them later and update this section accordingly.
- CSS1:
h3 - XPATH1:
//h3
A list of available update packages is provided at https://updater.factorio.com/get-available-versions.