Wie die Versionierung der Sally API funktioniert

Die Version der Sally API ist das erste Pfadsegment: /v1.0. Ein gleitendes /v1 gibt es bewusst nicht, ein notierter Pfad bedeutet also weiterhin das, was er bedeutet hat. Diese Seite erklärt, was das Einfrieren einer Version heißt und welche Änderungen eine neue Version bekommen.

Außerdem zeigt sie, wie du die Version in einer einzigen Konstante hältst, damit der Wechsel auf eine spätere Version in deinem Code eine Änderung in einer Zeile ist.

Schnellnavigation

1. Die aktuelle Version
2. Was Einfrieren heißt
3. Was keine neue Version bekommt
4. Die Ausnahme: der Health Check
5. Die Basis-URL an einer Stelle halten

1. Die aktuelle Version

Version	Status	Pfad
1.0	Aktuell, wird aktiv weiterentwickelt, noch nicht eingefroren	/v1.0

Wichtig

Version 1.0 kann sich noch so ändern, dass ein Client bricht. Betrachte sie vorerst als beweglich. Jede Änderung steht in den Release Notes. Wir sagen Bescheid, sobald die Version eingefroren ist.

2. Was Einfrieren heißt

Ist eine Version eingefroren, antwortet sie für immer genau so wie in diesem Moment und wird nie wieder geändert. Weitergearbeitet wird an der nächsten Version (/v1.1), und wer das alte Verhalten will, bleibt einfach auf seinem Pfad. Ein Umbau, der dafür zu groß ist, wird eine neue Hauptversion (/v2).

3. Was keine neue Version bekommt

Eine neue Version entsteht nur für eine Änderung, die einen Client brechen könnte. Eine rein ergänzende Änderung bekommt keine: Ein neuer Endpunkt, ein neues Feld oder ein neuer Enum-Wert erscheint in der Version, die du ohnehin nutzt.

Änderung	Neue Version?	Wo sie erscheint
Neuer Endpunkt	Nein	In der Version, die du schon nutzt
Neues Feld in einer Antwort	Nein	In der Version, die du schon nutzt
Neuer Enum-Wert	Nein	In der Version, die du schon nutzt
Änderung, die einen Client brechen könnte	Ja	In der nächsten Version, etwa /v1.1
Umbau, der dafür zu groß ist	Ja, eine neue Hauptversion	/v2

Wichtig

Dein Client muss deshalb zweierlei vertragen: Felder, die er nicht kennt, und Enum-Werte, die er noch nie gesehen hat. Ein Parser, der eines von beidem ablehnt, bricht an einer Änderung, die harmlos gedacht war.

Solange 1.0 nicht eingefroren ist, beschreibt diese Tabelle die Regel für eingefrorene Versionen. Bis dahin schau vor jedem Update deiner Anbindung in die Release Notes.

4. Die Ausnahme: der Health Check

GET /health trägt bewusst keine Version. Eine Verfügbarkeitsprüfung sagt nichts über den Vertrag, und ein Monitor sollte einem Versionswechsel nicht folgen müssen. Ein Token braucht sie auch nicht.

5. Die Basis-URL an einer Stelle halten

Leg die Version in eine einzige Konstante und bau jeden Pfad daraus. Kommt eine spätere Version, änderst du eine Zeile und sonst nichts:

cURL

SALLY_API="https://api.sally.io/v1.0"

curl "$SALLY_API/me" -H "Authorization: Bearer $SALLY_TOKEN"
curl "$SALLY_API/directories/$DIRECTORY_ID/recordings" -H "Authorization: Bearer $SALLY_TOKEN"

# Der Health Check hat keine Version
curl "https://api.sally.io/health"

JavaScript

const SALLY_API = 'https://api.sally.io/v1.0';

async function sally(path) {
  const response = await fetch(`${SALLY_API}${path}`, {
    headers: {Authorization: `Bearer ${process.env.SALLY_TOKEN}`},
  });
  return response.json();
}

const me = await sally('/me');
const recordings = await sally(`/directories/${directoryId}/recordings`);

Python

import os
import requests

SALLY_API = "https://api.sally.io/v1.0"

def sally(path):
    response = requests.get(
        f"{SALLY_API}{path}",
        headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    )
    return response.json()

me = sally("/me")
recordings = sally(f"/directories/{directory_id}/recordings")

Empfehlung

Lies Antworten in Objekte, die unbekannte Felder ignorieren, und gib jedem Enum einen Ausweichzweig für Werte, die du noch nicht kennst. Dann können neue Felder und Enum-Werte in derselben Version deine Anbindung nicht brechen.