In other languages:

Mod details API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(initial mod details API documentation)
 
mNo edit summary
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Experimental|Experimental API]]</div>
<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Public|Public API]]</div>


The mod details API is used the change mod information like the description on the Factorio mod portal. It requires an API key with the <code>ModPortal: Edit Mods</code> usage, which can be created on https://factorio.com/profile.  
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 <code>ModPortal: Edit Mods</code> usage, which can be created on https://factorio.com/profile.  


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


== Endpoint ==
== Endpoint ==
Line 11: Line 10:
{| class="wikitable"
{| class="wikitable"
|-
|-
| URL || https://mods.factorio.com/api/experimental/mods/edit_details  
| URL || https://mods.factorio.com/api/v2/mods/edit_details  
|-
|-
| HTTP Method || <code>POST</code>  
| HTTP Method || <code>POST</code>  
Line 28: Line 27:
| mod || string, mandatory || Internal name of the mod whose details are to be changed
| mod || string, mandatory || Internal name of the mod whose details are to be changed
|-
|-
| title || string, optional || Display name of the mod
| title || string, optional || Display name of the mod. Min length 1, max length 250
|-
|-
| summary || string, optional || Short description of the mod
| summary || string, optional || Short description of the mod. Max length 500
|-
|-
| description || string, optional || Long description of the mod in markdown format
| description || string, optional || Long description of the mod in markdown format
|-
|-
| category || enum, optional || Mod category, see [[#Category]]
| category || enum, optional || Mod category, see [[#Category]]
|-
| tags || enum, optional, multiple possible || Mod tags, see [[#Tags]]
|-
|-
| license || enum, optional || Mod license, see [[#License]]
| license || enum, optional || Mod license, see [[#License]]
|-
|-
| homepage || strong, optional || URL of mod homepage
| 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 || strong, optional || URL of mod source code repository
| 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 58: Line 59:
| message || string || This attribute only appears on <strong>failed</strong> requests. Has details about the problem.
| message || string || This attribute only appears on <strong>failed</strong> requests. Has details about the problem.
|}
|}
== Possible API Error Responses ==
== Possible API Error Responses ==
Possible values for the <code>error</code> property of API responses
Possible values for the <code>error</code> property of API responses
Line 79: Line 81:
{| class="wikitable"
{| class="wikitable"
! Value !! Name !! Description
! Value !! Name !! Description
|-
|<code><empty string></code>|| No category ||
|-
|<code>general</code>|| General || Mods that cannot be sorted into other categories
|-
|-
|<code>non-game-changing</code>|| Non-Game-Changing || Changes only look&feel. New graphics, new sounds, etc.
|<code><empty string></code>|| No category
|-
|-
|<code>helper-mods</code>|| Helper Mods || These mods are not game-changing, but enhance the gameplay by helping you with useful functions. Mods like showing the current game-time, keep track over your resources, rail-laying...
|<code>content</code>|| Content || Mods introducing new content into the game.  
|-
|-
|<code>transportation</code>|| Transportation || Player transport
|<code>overhaul</code>|| Overhaul || Large total conversion mods.
|-
|-
|<code>logistics</code>|| Logistics || Transport of materials
|<code>tweaks</code>|| Tweaks || Small changes concerning balance, gameplay, or graphics.
|-
|-
|<code>utility</code>|| Utility || Helps with certain things the player is doing.
|<code>utilities</code>|| Utilities || Providing the player with new tools or adjusting the game interface, without fundamentally changing gameplay.  
|-
|-
|<code>balancing</code>|| Balancing ||  
|<code>scenarios</code>|| Scenarios || Scenarios, maps, and puzzles.
|-
|-
|<code>weapons</code>|| Weapons ||  
|<code>mod-packs</code>|| Mod packs || Collections of mods with tweaks to make them work together.
|-
|-
|<code>enemies</code>|| Enemies ||  
|<code>localizations</code>|| Localizations || Translations for other mods.
|-
|-
|<code>armor</code>|| Armor || Armors or armor equipment related.
|<code>internal</code>|| Internal || Lua libraries for use by other mods and submods that are parts of a larger mod.  
|-
|-
|<code>oil</code>|| Oil || Things related to oil related manufacture
|}
 
=== Tags ===
 
{| class="wikitable"
! Value !! Name !! Description
|-
|-
|<code>logistic-network</code>|| Logistic network || Related to roboports and logistic robots
|<code>transportation</code>|| Transportation || Transportation of the player, be it vehicles or teleporters.
|-
|-
|<code>circuit-network</code>|| Circuit network ||  
|<code>logistics</code>|| Logistics || Augmented or new ways of transporting materials - belts, inserters, pipes!
|-
|-
|<code>storage</code>|| Storage ||  
|<code>trains</code>|| Trains || Trains are great, but what if they could do even more?
|-
|-
|<code>power-production</code>|| Power production ||  
|<code>combat</code>|| Combat || New ways to deal with enemies, be it attack or defense.
|-
|-
|<code>manufacture</code>|| Manufacture || Furnaces, assembling machines, production chains
|<code>armor</code>|| Armor || Armors or armor equipment.
|-
|-
|<code>blueprints</code>|| Blueprints ||  
|<code>enemies</code>|| Enemies || Changes to enemies or entirely new enemies to deal with.
|-
|-
|<code>cheats</code>|| Cheats ||  
|<code>environment</code>|| Environment || Map generation and terrain modification.
|-
|-
|<code>defense</code>|| Defense ||  
|<code>mining</code>|| Mining || New Ores and resources as well as machines.
|-
|-
|<code>mining</code>|| Mining ||  
|<code>fluids</code>|| Fluids || Things related to oil and other fluids.
|-
|-
|<code>environment</code>|| Environment ||  
|<code>logistic-network</code>|| Logistic network || Related to roboports and logistic robots.
|-
|-
|<code>info</code>|| Info || Mods that provide additional information to the player
|<code>circuit-network</code>|| Circuit network || Entities which interact with the circuit network.
|-
|-
|<code>trains</code>|| Trains ||  
|<code>manufacturing</code>|| Manufacturing || Furnaces, assembling machines, production chains.
|-
|-
|<code>big-mods</code>|| Big mods || Too big and/or changes too much of the game to be fit anywhere else
|<code>power</code>|| Power || Changes to power production and distribution.
|-
|-
|<code>scenarios</code>|| Scenarios || Story mode campaigns on a premade map
|<code>storage</code>|| Storage || More than just chests.
|-
|-
|<code>mod-packs</code>|| Mod packs || Collections of mods with tweaks to make them work together!
|<code>blueprints</code>|| Blueprints || Change blueprint behavior.
|-
|-
|<code>libraries</code>|| Libraries || Mods used by other mods
|<code>cheats</code>|| Cheats || Play it your way.
|-
|-
|}
|}
=== License ===
=== License ===


Line 164: Line 168:


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


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


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



Latest revision as of 09:25, 20 December 2022

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
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}")