Mod details API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(fix error in python example)
(Removed {{Languages}})
 
(2 intermediate revisions by one other user not shown)
Line 39: Line 39:
| license || enum, optional || Mod license, see [[#License]]
| license || enum, optional || Mod license, see [[#License]]
|-
|-
| homepage || string, optional || URL of mod homepage (URL must use <code>http</code> or <code>https</code> scheme). Max length 256
| homepage || string, optional || URL of mod homepage (URL must use <code>http</code> or <code>https</code> scheme), max length 256
|-
|-
| deprecated || bool, optional || Deprecated flag to hide mod from public listings
| deprecated || bool, optional || Deprecated flag to hide mod from public listings
|-
|-
| source_url || string, optional || URL of mod source code repository (URL must use <code>http</code> or <code>https</code> scheme)
| source_url || string, optional || URL of mod source code repository (URL must use <code>http</code> or <code>https</code> scheme), max length 256
|-
|-
| faq || string, optional || FAQ for the mod in markdown format
| faq || string, optional || FAQ for the mod in markdown format
Line 83: Line 83:
|-
|-
|<code><empty string></code>|| No category  
|<code><empty string></code>|| No category  
|-
|<code>no-category</code>|| No category
|-
|-
|<code>content</code>|| Content || Mods introducing new content into the game.  
|<code>content</code>|| Content || Mods introducing new content into the game.  
Line 185: Line 187:
</syntaxhighlight>
</syntaxhighlight>


{{Languages}}[[Category:Technical]]
[[Category:Technical]]

Latest revision as of 09:06, 12 November 2023

Category: Public API

The mod details API is used to change mod information like the description on the Factorio mod portal. It requires an API key with the ModPortal: Edit Mods usage, which can be created on https://factorio.com/profile.

It accepts multipart/form-data HTTP requests and responds with JSON encoded objects.

Endpoint

edit_details

URL https://mods.factorio.com/api/v2/mods/edit_details
HTTP Method POST


HTTP Request Header

Authorization Bearer $APIKey Authorization header with the APIKey and a "Bearer " prefix -> "Bearer $APIKey"


HTTP Request Body

mod string, mandatory Internal name of the mod whose details are to be changed
title string, optional Display name of the mod. Min length 1, max length 250
summary string, optional Short description of the mod. Max length 500
description string, optional Long description of the mod in markdown format
category enum, optional Mod category, see #Category
tags enum, optional, multiple possible Mod tags, see #Tags
license enum, optional Mod license, see #License
homepage string, optional URL of mod homepage (URL must use http or https scheme), max length 256
deprecated bool, optional Deprecated flag to hide mod from public listings
source_url string, optional URL of mod source code repository (URL must use http or https scheme), max length 256
faq string, optional FAQ for the mod in markdown format


JSON object response

success bool This attribute only appears for successful requests. It's set to true.
url string This attribute only appears for successful requests. URL path to get mod details endpoint
error string This attribute only appears on failed requests.
message string This attribute only appears on failed requests. Has details about the problem.

Possible API Error Responses

Possible values for the error property of API responses

InvalidApiKey Missing or invalid API key for the current endpoint
InvalidRequest Invalid request.
InternalError Internal error, please try again later.
Forbidden Insufficent permission for current endpoint
Unknown Unknown error, please try again later.
UnknownMod Mod does not exist in mod portal

Enums

Category

Value Name Description
<empty string> No category
no-category No category
content Content Mods introducing new content into the game.
overhaul Overhaul Large total conversion mods.
tweaks Tweaks Small changes concerning balance, gameplay, or graphics.
utilities Utilities Providing the player with new tools or adjusting the game interface, without fundamentally changing gameplay.
scenarios Scenarios Scenarios, maps, and puzzles.
mod-packs Mod packs Collections of mods with tweaks to make them work together.
localizations Localizations Translations for other mods.
internal Internal Lua libraries for use by other mods and submods that are parts of a larger mod.

Tags

Value Name Description
transportation Transportation Transportation of the player, be it vehicles or teleporters.
logistics Logistics Augmented or new ways of transporting materials - belts, inserters, pipes!
trains Trains Trains are great, but what if they could do even more?
combat Combat New ways to deal with enemies, be it attack or defense.
armor Armor Armors or armor equipment.
enemies Enemies Changes to enemies or entirely new enemies to deal with.
environment Environment Map generation and terrain modification.
mining Mining New Ores and resources as well as machines.
fluids Fluids Things related to oil and other fluids.
logistic-network Logistic network Related to roboports and logistic robots.
circuit-network Circuit network Entities which interact with the circuit network.
manufacturing Manufacturing Furnaces, assembling machines, production chains.
power Power Changes to power production and distribution.
storage Storage More than just chests.
blueprints Blueprints Change blueprint behavior.
cheats Cheats Play it your way.

License

Value Name Description URL
default_mit MIT A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty. https://opensource.org/licenses/MIT
default_gnugplv3 GNU GPLv3 The GNU GPL is the most widely used free software license and has a strong copyleft requirement. When distributing derived works, the source code of the work must be made available under the same license. https://opensource.org/licenses/gpl-3.0
default_gnulgplv3 GNU LGPLv3 Version 3 of the GNU LGPL is an additional set of permissions to the GNU GPLv3 license that requires that derived works be licensed under the same license, but works that only link to it do not fall under this restriction. https://opensource.org/licenses/lgpl-3.0
default_mozilla2 Mozilla Public License 2.0 The Mozilla Public License (MPL 2.0) is maintained by the Mozilla foundation. This license attempts to be a compromise between the permissive BSD license and the reciprocal GPL license. https://opensource.org/licenses/mpl-2.0
default_apache2 Apache License 2.0 A permissive license that also provides an express grant of patent rights from contributors to users. https://opensource.org/licenses/apache-2.0
default_unlicense The Unlicense (Public Domain) Because copyright is automatic in most countries, the Unlicense is a template to waive copyright interest in software you've written and dedicate it to the public domain. Use the Unlicense to opt out of copyright entirely. It also includes the no-warranty statement from the MIT/X11 license. http://unlicense.org/
custom_$ID Custom Custom license. The ID can be taken from the edit URL on the "My licenses" page on the mod portal. mods.factorio.com/licenses/edit/$ID https://mods.factorio.com/licenses

Python Example

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
EDIT_MOD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/edit_details"

apikey = getenv("MOD_EDIT_API_KEY")
modname = getenv("MOD_NAME")

request_body = {"mod": modname, "faq": "# hello world", "tags": ["power", "storage"], "category": "tweaks"}
request_headers = {"Authorization": f"Bearer {apikey}"}

response = requests.post(EDIT_MOD_URL, data=request_body, headers=request_headers)

if not response.ok:
    print(f"edit failed: {response.text}")
    sys.exit(1)

print(f"edit successful: {response.text}")