Skip to content

Data Api

BluePsyduck edited this page Feb 19, 2021 · 1 revision

The Data API is one of the most important components, as it provides access to all the data of the mod combinations, using a JSON based interface. Historically (and internally) the "Data API" is only called "API", because it was the first one created and is still the most important one.

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

System architecture

The Data API uses a MySQL database to store all the data to all known combinations of mods. This database will grow as more and more combinations get imported into it.

The Data API itself is only reading from its database (except a caching table). Only the Data API Import is actually writing new data to the database, making it the active companion to the passive API.

The consumers of the Data API and thus of all the data are the Portal API as well as other external tools. From the view point of the Data API the Portal API is like any other external tool, it does not have any special privileges. This means everything you see in the FIB can be achieved with any other tool as well.

Combination of mods

All data in the database is identified by the combination ids. A combination id is a representation of a combination of mods, and gets calculated by the Combination Api. The combination id must be specified in every request to the Data API.

The most basic combination is the Vanilla Factorio game, consisting only of the "base" mod. Its combination id is 2f4a45fa-a509-a9d1-aae6-ffcf984a7a76.

Authorization

The Data API uses API keys to identify the consumers. Without an API key, it will still provide access to the Vanilla combination, but it will refuse to provide any data to other combinations. This is so that interested developers may look into the API and trigger actual requests without requiring an API key first.

Localisation

The Data API supports all languages of the Factorio game, and will translate labels and descriptions as long as the mods are providing the translations themselves. Missing translations will automatically be replaced with English as they would in-game. Missing English translations will result in empty strings. The Data API will not replace missing translations with some placeholder as the game would do.

The language must be specified in each request using the Accept-Language header. The values must be those used by Factorio, the Data API will not try to find a best-match. E.g. for German the value must be "de" and not "de-DE", "deu" or "dt", because Factorio internally uses "de". Default language is "en".