Skip to content
xivapi

Ensuring Stability

As outlined in important concepts, new game versions may result in arbitrary breaking changes, and schemas may receive changes from the community to fix or improve them.

Either of the above may affect how the API structures data in responses - in turn, breaking any code utilising the API that relies on that structure.

This service supports schema pins, but not historical game-version selection for sheet or search requests. A schema pin fixes field names and mappings; it does not freeze the data or guarantee compatibility after a game update. Assets have a separate snapshot selection mechanism.

Game Versions

Section titled “Game Versions”

Sheet and search requests always use the latest locally activated data release. Their version query parameter is ignored. The version value in a response is the release title, not an upstream version hash, and cannot be used to request historical sheet data.

GET /api/version (also /api/versions) lists retained local releases and the update status. This list is informational, not a list of queryable historical versions. See the API reference.

Asset endpoints accept version=latest or a full game version with a published asset index. These snapshots are independent of sheet releases; see Retrieving Assets.

Schemas

Section titled “Schemas”

API endpoints that serve sheet data additionally accept a schema parameter. The schema specified will be used when reading data from sheets, and to interpret any field filters provided. If omitted, the most recent schema for the active data release will be used.

Successful sheet-row and search responses include a schema value in the response object. The value is considered to be the canonical specifier for the schema that was used for the request - as such, it’s recommended to take note of the value, and use it if planning to pin the schema. Efforts are made to ensure the canonical specifier is the most stable representation of the schema at a point in time.

The API is built to support multiple community schema sources. At time of writing, EXDSchema is the only actively supported source, see below for details on its usage.

EXDSchema

Section titled “EXDSchema”

The EXDSchema git repository tracks sheet schemas across game versions, and is increasingly widely used throughout the FFXIV developer community. XIVAPI offers a few approaches for specifying what EXDSchema mapping you wish to use.

exdschema@2:ver:request
Picks the most recent schema available for the active data release’s game version.
exdschema@2:rev:<revision>
Uses the schema as of the specified git revision.

EXDSchema uses the exdschema@2:rev:<revision> form for canonical specifiers, with the full SHA-1 object name for the resolved commit as the revision.

Example

Section titled “Example”

Among other changes, commit c44cfd2 renamed WorldDCGroupType’s Unknown0 field to NeolobbyId. A schema pin can be used to observe that c44cfd2 contains these changes, and that the parent commit 22f45f4 does not.

// /api/sheet/WorldDCGroupType/9? \
//   fields=Unknown0,NeolobbyId&schema=exdschema@2:rev:c44cfd2
{
  "schema": "exdschema@2:rev:c44cfd270a72248293e242b4950b2ddeff9e49f2",
  "fields": { "NeolobbyId": 9 }
}


// /api/sheet/WorldDCGroupType/9? \
//   fields=Unknown0,NeolobbyId&schema=exdschema@2:rev:22f45f4
{
  "schema": "exdschema@2:rev:22f45f4d6aab0c8722f5c0a6eabceb1e2a13c12c",
  "fields": { "Unknown0": 9 }
}