Combination Api

The Combination API operates on a metadata level of combinations: It knows about all the combinations and of what mods they are built of, but does actually not know any additional data like items and recipes.

Additionally, the Combination API also provides the ability to create export jobs for a combination, and manages them in a queue-like fashion. Other components can ask the Combination API for jobs in a specific state to continue the export process, yet the Combination API does not take any active part in the process beside storing the export jobs.

OpenAPI specification: https://docs.factorio-item-browser.com/combination-api

System architecture

The Combination API has its own database for two purposes: Store already known combinations with their mods, so e.g. getting the list of mods from a combination id is possible, and managing the export jobs.

While the Data API has the Factorio game as its only data source, the Combination API uses the Factorio Mod Portal (or rather its API) to get all required data about mods.

Next to that, there are three internal components of the FIB using the Combination API:

• Portal API: The Portal API will add new export jobs to the queue whenever it is needed. The Portal API is the only source of new export jobs, no other component will create any. Additionally, the Portal API will check the status of the export jobs to provide it to the Portal Frontend and thus the user.

• Export: The Export will look for any jobs with the status queued, and will process them one after another. It will update the status several times to signal the process of the export job, eventually setting it to uploaded when finished.

• Data API Import: The Data API Import will look for any jobs with the status uploaded, signaling that the data has been in fact uploaded to the FTP space. It will import the data of these jobs into the database of the API, updating the job status to eventually read done.

For further details on the states of an export job, see Export Job State Flow

Identifying a Combination

The Combination API supports several ways of identifying a combination:

• Mod Names: The names of the mods can be provided as a comma-separated list. The API will calculate the id from the mods, and provide the details for the combination. If the combination is not known, it will be created in the local database.

• Combination Id: If the combination id is already known, then it can of course be used to get the details of the combination. Note that the combination must have been requested at least once through its mod names to make the combination id known to the API itself. The combination id is a UUID in its standardized representation. This representation is e.g. used in the main API to identify the desired combination for the request.

• Short Combination Id: Instead of the UUID representation of the Combination Id, the short one compresses the id into 22 characters, utilizing numbers as well as the uppercase and lowercase alphabet, making the id encode in base62. Other than the representation format, there is no difference between the two combination ids. This representation is e.g. used in the Portal Frontend to make the URLs a little shorter with the combination id in it.