Mod images API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(Created page with "<div align="center" class="stub">'''Category:''' Experimental API</div> The mod images API is used to add, reorder or remov...")
 
(fixed formatting)
 
(6 intermediate revisions by 5 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 images API is used to add, reorder or remove mod images 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 images API is used to add, reorder or remove mod images 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.  


Line 9: Line 9:


{| class="wikitable"
{| class="wikitable"
|-
| URL || https://mods.factorio.com/api/v2/mods/images/add
| URL || https://mods.factorio.com/api/experimental/mods/images/add
|-
|-
| HTTP Method || <code>POST</code>  
| HTTP Method || <code>POST</code>  
|-
|}
|}


Line 53: Line 51:
| id || string || This attribute only appears on <strong>successful</strong> uploads. SHA1 of the uploaded image.
| id || string || This attribute only appears on <strong>successful</strong> uploads. SHA1 of the uploaded image.
|-
|-
| url || bool || This attribute only appears on <strong>successful</strong> uploads. Url of the uploaded image.
| url || string || This attribute only appears on <strong>successful</strong> uploads. Url of the uploaded image.
|-
|-
| thumbnail || bool || This attribute only appears on <strong>successful</strong> uploads. Url of thumbnail of the uploaded image.
| thumbnail || string || This attribute only appears on <strong>successful</strong> uploads. Url of thumbnail of the uploaded image.
|-
|-
| error || string || This attribute only appears on <strong>failed</strong> uploads.
| error || string || This attribute only appears on <strong>failed</strong> uploads.
Line 65: Line 63:
{| class="wikitable"
{| class="wikitable"
|-
|-
| URL || https://mods.factorio.com/api/experimental/mods/images/edit
| URL || https://mods.factorio.com/api/v2/mods/images/edit
|-
|-
| HTTP Method || <code>POST</code>  
| HTTP Method || <code>POST</code>  
Line 78: Line 76:
HTTP Request Body
HTTP Request Body
{| class="wikitable"
{| class="wikitable"
|-
| mod || string || Name of the mod, for which a new image will be uploaded
| mod || string || Name of the mod, for which a new image will be uploaded
|-
| images || string || List of comma-seperated image ids that should be displayed on the mod page
| images || string || List of comma-seperated image ids that should be displayed on the mod page
|-
|}
|}


Line 122: Line 123:


MOD_PORTAL_URL = "https://mods.factorio.com"
MOD_PORTAL_URL = "https://mods.factorio.com"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/experimental/mods/images/add"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/images/add"


apikey = getenv("MOD_EDIT_API_KEY")
apikey = getenv("MOD_EDIT_API_KEY")
Line 158: Line 159:


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


apikey = getenv("MOD_EDIT_API_KEY")
apikey = getenv("MOD_EDIT_API_KEY")
Line 178: Line 179:


</syntaxhighlight>
</syntaxhighlight>
{{Languages}}[[Category:Technical]]
[[Category:Technical]]

Latest revision as of 20:35, 13 November 2023

Category: Public API

The mod images API is used to add, reorder or remove mod images 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.

Endpoints

add

URL https://mods.factorio.com/api/v2/mods/images/add
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 Name of the mod, for which a new image will be uploaded

JSON object response

upload_url string URL the image should be uploaded to
error string This attribute only appears on failed requests.
message string This attribute only appears on failed requests. Has details about the problem.

finish_upload

URL $upload_url URL returned by the add endpoint
HTTP Method POST

HTTP Request Body

image Image file

JSON object response

id string This attribute only appears on successful uploads. SHA1 of the uploaded image.
url string This attribute only appears on successful uploads. Url of the uploaded image.
thumbnail string This attribute only appears on successful uploads. Url of thumbnail of the uploaded image.
error string This attribute only appears on failed uploads.
message string This attribute only appears on failed uploads. Has details about the problem.

edit

URL https://mods.factorio.com/api/v2/mods/images/edit
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 Name of the mod, for which a new image will be uploaded
images string List of comma-seperated image ids that should be displayed on the mod page


JSON object response

success bool This attribute only appears on successful uploads. It's set to true.
images list This attribute only appears on successful uploads. List of objects with id, url and thumbnail attribute same as finish_upload endpoint.
error string This attribute only appears on failed uploads.
message string This attribute only appears on failed uploads. 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.
InvalidImageUpload Invalid image file uploaded.
UnknownMod Mod does not exist in mod portal

Python Examples

Add Image

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/images/add"

apikey = getenv("MOD_EDIT_API_KEY")
modname = sys.argv[1]
filepath = sys.argv[2]

request_body = data = {"mod": modname}
request_headers = {"Authorization": f"Bearer {apikey}"}

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

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

upload_url = response.json()["upload_url"]

with open(filepath, "rb") as f:
    request_body = {"image": f}
    response = requests.post(upload_url, files=request_body)

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

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

Edit Images

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/images/edit"

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

image_ids = ["fdc375d5ca3c263fedafb7ef143c82f9fb668472", "47bda5cd27ef49fe86fe03f803cb5c351a848586"]
image_ids_text = ",".join(image_ids)

request_body = data = {"mod": modname, "images": image_ids_text}
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}")