348 lines
11 KiB
Markdown
348 lines
11 KiB
Markdown
# API Guide
|
|
|
|
Archipelago has a rudimentary API that can be queried by endpoints. The API is a work-in-progress and should be improved over time.
|
|
|
|
The following API requests are formatted as: `https://<Archipelago URL>/api/<endpoint>`
|
|
|
|
The returned data will be formated in a combination of JSON lists or dicts, with their keys or values being notated in `blocks` (if applicable)
|
|
|
|
Current endpoints:
|
|
- Datapackage API
|
|
- [`/datapackage`](#datapackage)
|
|
- [`/datapackage/<string:checksum>`](#datapackagestringchecksum)
|
|
- [`/datapackage_checksum`](#datapackagechecksum)
|
|
- Generation API
|
|
- [`/generate`](#generate)
|
|
- [`/status/<suuid:seed>`](#status)
|
|
- Room API
|
|
- [`/room_status/<suuid:room_id>`](#roomstatus)
|
|
- User API
|
|
- [`/get_rooms`](#getrooms)
|
|
- [`/get_seeds`](#getseeds)
|
|
|
|
|
|
## Datapackage Endpoints
|
|
These endpoints are used by applications to acquire a room's datapackage, and validate that they have the correct datapackage for use. Datapackages normally include, item IDs, location IDs, and name groupings, for a given room, and are essential for mapping IDs received from Archipelago to their correct items or locations.
|
|
|
|
### `/datapackage`
|
|
<a name="datapackage"></a>
|
|
Fetches the current datapackage from the WebHost.
|
|
You'll receive a dict named `games` that contains a named dict of every game and its data currently supported by Archipelago.
|
|
Each game will have:
|
|
- A checksum `checksum`
|
|
- A dict of item groups `item_name_groups`
|
|
- Item name to AP ID dict `item_name_to_id`
|
|
- A dict of location groups `location_name_groups`
|
|
- Location name to AP ID dict `location_name_to_id`
|
|
|
|
Example:
|
|
```
|
|
{
|
|
"games": {
|
|
...
|
|
"Clique": {
|
|
"checksum": "0271f7a80b44ba72187f92815c2bc8669cb464c7",
|
|
"item_name_groups": {
|
|
"Everything": [
|
|
"A Cool Filler Item (No Satisfaction Guaranteed)",
|
|
"Button Activation",
|
|
"Feeling of Satisfaction"
|
|
]
|
|
},
|
|
"item_name_to_id": {
|
|
"A Cool Filler Item (No Satisfaction Guaranteed)": 69696967,
|
|
"Button Activation": 69696968,
|
|
"Feeling of Satisfaction": 69696969
|
|
},
|
|
"location_name_groups": {
|
|
"Everywhere": [
|
|
"The Big Red Button",
|
|
"The Item on the Desk"
|
|
]
|
|
},
|
|
"location_name_to_id": {
|
|
"The Big Red Button": 69696969,
|
|
"The Item on the Desk": 69696968
|
|
}
|
|
},
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### `/datapackage/<string:checksum>`
|
|
<a name="datapackagestringchecksum"></a>
|
|
Fetches a single datapackage by checksum.
|
|
Returns a dict of the game's data with:
|
|
- A checksum `checksum`
|
|
- A dict of item groups `item_name_groups`
|
|
- Item name to AP ID dict `item_name_to_id`
|
|
- A dict of location groups `location_name_groups`
|
|
- Location name to AP ID dict `location_name_to_id`
|
|
|
|
Its format will be identical to the whole-datapackage endpoint (`/datapackage`), except you'll only be returned the single game's data in a dict.
|
|
|
|
### `/datapackage_checksum`
|
|
<a name="datapackagechecksum"></a>
|
|
Fetches the checksums of the current static datapackages on the WebHost.
|
|
You'll receive a dict with `game:checksum` key-value pairs for all the current officially supported games.
|
|
Example:
|
|
```
|
|
{
|
|
...
|
|
"Donkey Kong Country 3":"f90acedcd958213f483a6a4c238e2a3faf92165e",
|
|
"Factorio":"a699194a9589db3ebc0d821915864b422c782f44",
|
|
...
|
|
}
|
|
```
|
|
|
|
|
|
## Generation Endpoint
|
|
These endpoints are used internally for the WebHost to generate games and validate their generation. They are also used by external applications to generate games automatically.
|
|
|
|
### `/generate`
|
|
<a name="generate"></a>
|
|
Submits a game to the WebHost for generation.
|
|
**This endpoint only accepts a POST HTTP request.**
|
|
|
|
There are two ways to submit data for generation: With a file and with JSON.
|
|
|
|
#### With a file:
|
|
Have your ZIP of yaml(s) or a single yaml, and submit a POST request to the `/generate` endpoint.
|
|
If the options are valid, you'll be returned a successful generation response. (see [Generation Response](#generation-response))
|
|
|
|
Example using the python requests library:
|
|
```
|
|
file = {'file': open('Games.zip', 'rb')}
|
|
req = requests.post("https://archipelago.gg/api/generate", files=file)
|
|
```
|
|
|
|
#### With JSON:
|
|
Compile your weights/yaml data into a dict. Then insert that into a dict with the key `"weights"`.
|
|
Finally, submit a POST request to the `/generate` endpoint.
|
|
If the weighted options are valid, you'll be returned a successful generation response (see [Generation Response](#generation-response))
|
|
|
|
Example using the python requests library:
|
|
```
|
|
data = {"Test":{"game": "Factorio","name": "Test","Factorio": {}},}
|
|
weights={"weights": data}
|
|
req = requests.post("https://archipelago.gg/api/generate", json=weights)
|
|
```
|
|
|
|
#### Generation Response:
|
|
##### Successful Generation:
|
|
Upon successful generation, you'll be sent a JSON dict response detailing the generation:
|
|
- The UUID of the generation `detail`
|
|
- The SUUID of the generation `encoded`
|
|
- The response text `text`
|
|
- The page that will resolve to the seed/room generation page once generation has completed `url`
|
|
- The API status page of the generation `wait_api_url` (see [Status Endpoint](#status))
|
|
|
|
Example:
|
|
```
|
|
{
|
|
"detail": "19878f16-5a58-4b76-aab7-d6bf38be9463",
|
|
"encoded": "GYePFlpYS3aqt9a_OL6UYw",
|
|
"text": "Generation of seed 19878f16-5a58-4b76-aab7-d6bf38be9463 started successfully.",
|
|
"url": "http://archipelago.gg/wait/GYePFlpYS3aqt9a_OL6UYw",
|
|
"wait_api_url": "http://archipelago.gg/api/status/GYePFlpYS3aqt9a_OL6UYw"
|
|
}
|
|
```
|
|
|
|
##### Failed Generation:
|
|
|
|
Upon failed generation, you'll be returned a single key-value pair. The key will always be `text`
|
|
The value will give you a hint as to what may have gone wrong.
|
|
- Options without tags, and a 400 status code
|
|
- Options in a string, and a 400 status code
|
|
- Invalid file/weight string, `No options found. Expected file attachment or json weights.` with a 400 status code
|
|
- Too many slots for the server to process, `Max size of multiworld exceeded` with a 409 status code
|
|
|
|
If the generation detects a issue in generation, you'll be sent a dict with two key-value pairs (`text` and `detail`) and a 400 status code. The values will be:
|
|
- Summary of issue in `text`
|
|
- Detailed issue in `detail`
|
|
|
|
In the event of an unhandled server exception, you'll be provided a dict with a single key `text`:
|
|
- Exception, `Uncought Exception: <error>` with a 500 status code
|
|
|
|
### `/status/<suuid:seed>`
|
|
<a name="status"></a>
|
|
Retrieves the status of the seed's generation.
|
|
This endpoint will return a dict with a single key-vlaue pair. The key will always be `text`
|
|
The value will tell you the status of the generation:
|
|
- Generation was completed: `Generation done` with a 201 status code
|
|
- Generation request was not found: `Generation not found` with a 404 status code
|
|
- Generation of the seed failed: `Generation failed` with a 500 status code
|
|
- Generation is in progress still: `Generation running` with a 202 status code
|
|
|
|
## Room Endpoints
|
|
Endpoints to fetch information of the active WebHost room with the supplied room_ID.
|
|
|
|
### `/room_status/<suuid:room_id>`
|
|
<a name="roomstatus"></a>
|
|
Will provide a dict of room data with the following keys:
|
|
- Tracker SUUID (`tracker`)
|
|
- A list of players (`players`)
|
|
- Each item containing a list with the Slot name and Game
|
|
- Last known hosted port (`last_port`)
|
|
- Last activity timestamp (`last_activity`)
|
|
- The room timeout counter (`timeout`)
|
|
- A list of downloads for files required for gameplay (`downloads`)
|
|
- Each item is a dict containings the download URL and slot (`slot`, `download`)
|
|
|
|
Example:
|
|
```
|
|
{
|
|
"downloads": [
|
|
{
|
|
"download": "/slot_file/kK5fmxd8TfisU5Yp_eg/1",
|
|
"slot": 1
|
|
},
|
|
{
|
|
"download": "/slot_file/kK5fmxd8TfisU5Yp_eg/2",
|
|
"slot": 2
|
|
},
|
|
{
|
|
"download": "/slot_file/kK5fmxd8TfisU5Yp_eg/3",
|
|
"slot": 3
|
|
},
|
|
{
|
|
"download": "/slot_file/kK5fmxd8TfisU5Yp_eg/4",
|
|
"slot": 4
|
|
},
|
|
{
|
|
"download": "/slot_file/kK5fmxd8TfisU5Yp_eg/5",
|
|
"slot": 5
|
|
}
|
|
],
|
|
"last_activity": "Fri, 18 Apr 2025 20:35:45 GMT",
|
|
"last_port": 52122,
|
|
"players": [
|
|
[
|
|
"Slot_Name_1",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_2",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_3",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_4",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_5",
|
|
"Ocarina of Time"
|
|
]
|
|
],
|
|
"timeout": 7200,
|
|
"tracker": "cf6989c0-4703-45d7-a317-2e5158431171"
|
|
}
|
|
```
|
|
|
|
## User Endpoints
|
|
User endpoints can get room and seed details from the current session tokens (cookies)
|
|
|
|
### `/get_rooms`
|
|
<a name="getrooms"></a>
|
|
Retreives a list of all rooms currently owned by the session token.
|
|
Each list item will contain a dict with the room's details:
|
|
- Room SUUID (`room_id`)
|
|
- Seed SUUID (`seed_id`)
|
|
- Creation timestamp (`creation_time`)
|
|
- Last activity timestamp (`last_activity`)
|
|
- Last known AP port (`last_port`)
|
|
- Room timeout counter in seconds (`timeout`)
|
|
- Room tracker SUUID (`tracker`)
|
|
|
|
Example:
|
|
```
|
|
[
|
|
{
|
|
"creation_time": "Fri, 18 Apr 2025 19:46:53 GMT",
|
|
"last_activity": "Fri, 18 Apr 2025 21:16:02 GMT",
|
|
"last_port": 52122,
|
|
"room_id": "90ae5f9b-177c-4df8-ac53-9629fc3bff7a",
|
|
"seed_id": "efbd62c2-aaeb-4dda-88c3-f461c029cef6",
|
|
"timeout": 7200,
|
|
"tracker": "cf6989c0-4703-45d7-a317-2e5158431171"
|
|
},
|
|
{
|
|
"creation_time": "Fri, 18 Apr 2025 20:36:42 GMT",
|
|
"last_activity": "Fri, 18 Apr 2025 20:36:46 GMT",
|
|
"last_port": 56884,
|
|
"room_id": "14465c05-d08e-4d28-96bd-916f994609d8",
|
|
"seed_id": "a528e34c-3b4f-42a9-9f8f-00a4fd40bacb",
|
|
"timeout": 7200,
|
|
"tracker": "4e624bd8-32b6-42e4-9178-aa407f72751c"
|
|
}
|
|
]
|
|
```
|
|
|
|
### `/get_seeds`
|
|
<a name="getseeds"></a>
|
|
Retreives a list of all seeds currently owned by the session token.
|
|
Each item in the list will contain a dict with the seed's details:
|
|
- Seed SUUID (`seed_id`)
|
|
- Creation timestamp (`creation_time`)
|
|
- A list of player slots (`players`)
|
|
- Each item in the list will contain a list of the slot name and game
|
|
|
|
Example:
|
|
```
|
|
[
|
|
{
|
|
"creation_time": "Fri, 18 Apr 2025 19:46:52 GMT",
|
|
"players": [
|
|
[
|
|
"Slot_Name_1",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_2",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_3",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_4",
|
|
"Ocarina of Time"
|
|
],
|
|
[
|
|
"Slot_Name_5",
|
|
"Ocarina of Time"
|
|
]
|
|
],
|
|
"seed_id": "efbd62c2-aaeb-4dda-88c3-f461c029cef6"
|
|
},
|
|
{
|
|
"creation_time": "Fri, 18 Apr 2025 20:36:39 GMT",
|
|
"players": [
|
|
[
|
|
"Slot_Name_1",
|
|
"Clique"
|
|
],
|
|
[
|
|
"Slot_Name_2",
|
|
"Clique"
|
|
],
|
|
[
|
|
"Slot_Name_3",
|
|
"Clique"
|
|
],
|
|
[
|
|
"Slot_Name_4",
|
|
"Archipelago"
|
|
]
|
|
],
|
|
"seed_id": "a528e34c-3b4f-42a9-9f8f-00a4fd40bacb"
|
|
}
|
|
]
|
|
```
|