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 remote is versioned if it has a folder remotes/<name>/ of <version>.yaml files, or versioned entries in the remotes mapping of the shared remotes/config.yaml. Each version is a complete remote config (url, routes, restricted, ...), so versions can point at different URLs or allow different routes.

# api_dock_config/remotes/config.yaml
remotes:
  core:
    description: Core API
    version: "0.5.0"
    url: https://api.example.com
  wolf:
    description: Wolves API          # defaults for every version below
    authors:
      - https://example.org/
    versions:
      - version: "1.0"
        url: https://api.wolves.example.com
        description: Stable          # overrides the default
      - version: "0.1"
        url: https://beta.api.wolves.example.com

• Each key is a remote name. version: gives one version, versions: a list (the remote's other keys are defaults each version overrides), and neither an unversioned remote.
• Versions from files and from remotes/config.yaml are combined. If both define the same version, the file wins. Here remotes/wolf/2.0.yaml would add a third version, and remotes/wolf/1.0.yaml would replace the inline 1.0.
• List the remote under remotes: in the main config either way. An entry that isn't listed isn't served (startup logs a warning).
• Startup fails if the file is malformed (both version and versions, a version defined twice, a version entry without version) or a listed remote's entry has no url.
• See Routing and Restrictions for the unversioned form.
• A version entry {from: <lookup>, version: "{{row.version}}", url: "{{row.url}}"} adds one version per row of a lookup.

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.
• Slugs and slug versions can also be generated from a lookup with a from: entry; generated versions count for latest and the version listing like any other. A version file or static slug wins over a generated version.
• 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 version in remotes/config.yaml or a slug). 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 lowest first, using the same ordering as latest.

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

How latest is chosen

latest resolves when the request arrives, to the highest version from files and inline definitions combined. Versions are compared the way people read them: each run of digits is compared as a number and each run of letters as text, and separators (., -, _) are ignored.

Versions	latest
2.4, 3.0	3.0
0.9, 0.10	0.10
1.9.0, 1.10.0	1.10.0
1.0, 1.0.1	1.0.1
2.0rc1, 2.0	2.0 (letters after a number rank below the plain number)
v9, v10	v10

Names that are all letters (alpha, beta) compare as text.

Quote versions in YAML

YAML reads unquoted 5.0 and 5.10 as numbers. API Dock turns a version in remotes/config.yaml or a slug 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 and edits to remotes/config.yaml and slugs 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.