Versioning

Versioning

A remote or database can have several versions, each with its own config. This page covers how versions are defined, the URLs they get, how latest is chosen, and the version listing.

api_dock_config/
├── config.yaml          # remotes: [weather]   databases: [birdnet]
├── remotes/
│   └── weather/
│       ├── 0.1.yaml
│       └── 0.2.yaml
└── databases/
    └── birdnet/
        ├── 2.4.yaml
        └── 3.0.yaml

GET /birdnet/                       -> {"versions": ["2.4", "3.0"]}
GET /birdnet/2.4/detections         -> runs the detections route from birdnet/2.4.yaml
GET /birdnet/latest/detections      -> same route from birdnet/3.0.yaml
GET /weather/0.1/forecast           -> proxied using remotes/weather/0.1.yaml

Defining versions

Remotes. A folder remotes/<name>/ makes the remote versioned. Each <version>.yaml in it is a complete remote config (url, routes, restricted, ...), so versions can point at different URLs or allow different routes. List the folder name under remotes: in the main config.

Databases. A database is versioned if it has a folder databases/<name>/ of <version>.yaml files, or versioned entries in the slugs list of the shared databases/config.yaml:

# api_dock_config/databases/config.yaml
slugs:
  - name: owl
    versions:
      - version: "4.0"
        schema: owl_4p0
      - version: "5.0"
        schema: owl_5p0
  - name: birdnet
    version: "2.4"
    schema: birdnet_2p4

• Versions from files and from slugs are combined. If both define the same version, the file wins.
• List the database under databases: in the main config either way.
• A slug name can't mix versioned and unversioned entries. Slugs are covered in Shared Database Config.

The version string is the file name without .yaml (or the slug's version). Any string works: 2.4, 0.5.0, 2.4v0.5.

URLs

Request	Versioned remote	Versioned database
/<name>/	{"versions": [...]}	{"versions": [...]}
/<name>/<version>/<path>	Proxied with that version's config	That version's route
/<name>/latest/<path>	Proxied with the latest version	The latest version's route
/<name>/<version>/	Proxied to the root of that version's url	{"routes": [...]} for that version
/<name>/<unknown>/...	404	404

The first path segment after the name must be a version or latest; anything else returns 404 ({"error": "Configuration for database 'birdnet' not found"}). The versions list is sorted as strings, so "0.10" comes before "0.9".

Unversioned remotes and databases have no version segment: /<name>/<path>.

How latest is chosen

latest resolves when the request arrives:

1. If every version string parses as a number (2.4, 3.0, 10), the highest number wins.
2. Otherwise all versions are compared as plain strings and the last in string order wins.

That rule has surprises:

Versions	latest	Why
2.4, 3.0	3.0	Numeric
0.9, 0.10	0.9	Numerically 0.10 is 0.1
1.9.0, 1.10.0	1.9.0	Not numbers, so string order; "1.9.0" > "1.10.0"
2.4, 2.4v0.5	2.4v0.5	One non-number switches the whole list to string order

If you rely on latest, choose version names that sort correctly under these rules (for example 0.09 and 0.10, or a fixed number of digits per part), or have clients request explicit versions.

Quote versions in YAML

YAML reads unquoted 5.0 and 5.10 as numbers. API Dock turns a slug's version into a string after YAML has parsed it, so version: 5.0 gives "5.0" but version: 5.10 gives "5.1". Quote versions wherever you write them in YAML:

slugs:
  - name: owl
    version: "5.10"    # not 5.10

File-based versions come from file names, so they are always strings.

Catalog include filters and shared-route include/exclude entries compare versions tolerantly (4, 4.0 and "4.0" all match a version named 4.0); see Catalog Endpoints and Shared Database Config.

Related

• New version files are picked up on the next request; no restart is needed (see Configuration). Database versions are only checked at startup.
• Every database version is checked at startup, including versions defined by slugs.
• Catalog Endpoints can list every name and version (they don't list latest).
• Restrictions in a versioned remote's file apply to that version only; see Routing and Restrictions.