Zum Inhalt

V1-Feldnamen — API v2

Bestehende Integrationen sprechen calServer oft in V1-Feldnamen an, den METTRACK-Codes wie C2301 oder I4201. V2 gibt denselben Feldern lesbare Namen (calibration_date, asset_number) — die V1-Codes bleiben dabei gültige Bezeichner. Ein Tool, das gegen V1 geschrieben wurde, muss seine Feldnamen also nicht anfassen.

Was ohne Zutun funktioniert

Filtern, sortieren und schreiben akzeptieren den V1-Code überall dort, wo auch der lesbare Name steht:

# Beide Anfragen liefern dasselbe
curl "…/api/v2/calibrations?filter[calibration_date]=2025-03-15" -H "$AUTH"
curl "…/api/v2/calibrations?filter[C2301]=2025-03-15"            -H "$AUTH"

# Sortieren ebenso
curl "…/api/v2/calibrations?sort=-C2301" -H "$AUTH"

# Schreiben ebenso
curl -X PUT "…/api/v2/calibrations/{id}" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"C2307": "M. Mustermann"}'

Schickt eine Anfrage beide Schreibweisen desselben Felds, gewinnt der lesbare Name — ein Client, der schon migriert hat, überschreibt sich damit nicht selbst mit einem alten Schlüssel, der noch im Code steht.

Was Sie einschalten müssen: V1-Namen in der Antwort

Antworten führen die Felder standardmäßig nur unter ihrem lesbaren Namen. Jedes Feld doppelt auszuliefern würde eine Inventarzeile um rund siebzig Schlüssel verlängern — auch für Clients, die das nie brauchen. Wer die Codes lesen will, fordert sie an:

curl "…/api/v2/calibrations?include_v1_names=1" -H "$AUTH"

curl "…/api/v2/calibrations" -H "$AUTH" \
  -H "X-CalServer-V1-Field-Names: 1"

Die Codes kommen zusätzlich, nicht anstelle der lesbaren Namen:

{
  "data": [
    {
      "id": "…",
      "type": "calibration",
      "attributes": {
        "calibration_date": "2025-03-15",
        "C2301": "2025-03-15",
        "technician": "M. Mustermann",
        "C2307": "M. Mustermann"
      }
    }
  ]
}

Der Header ist für Clients gedacht, die ihre URLs nicht anfassen können; der Query-Parameter für alles andere. Beide gelten für Listen und Einzelabrufe.

Grenzen

Ein V1-Code wird nicht aufgelöst, wenn er nicht eindeutig auf ein Feld zeigt. Das betrifft drei Fälle, und in allen dreien wäre die Alternative, sich für eine Zuordnung zu entscheiden — womit ein Tool am Ende in das falsche Feld schreibt:

  • Der Code ist zugleich der lesbare Name eines anderen Felds derselben Tabelle. Dann gewinnt das echte Feld.
  • Mehrere Felder derselben Tabelle beanspruchen denselben Code.
  • Zum Feld ist kein V1-Code hinterlegt — etwa bei Feldern, die es in V1 nie gab.

In diesen Fällen bleibt nur der lesbare Name.

Primärschlüssel sind keine Registry-Felder

Der eigene Schlüssel einer Tabelle steht nicht in der Feldverwaltung, also gibt es für ihn auch keinen Code zum Auflösen: filter[MTAG] auf /api/v2/inventories und filter[CTAG] auf /api/v2/calibrations werden verworfen und liefern damit alle Datensätze statt einer Fehlermeldung. Richtig ist filter[id]=… oder gleich der Pfad /api/v2/inventories/{mtag}. Als Fremdschlüssel funktioniert derselbe Code dagegen (filter[MTAG] auf /api/v2/calibrations trifft inventory_id). Ausführlich mit Beispielen: IDs: MTAG, CTAG und die anderen Tags. Welchen Code ein Feld trägt,

steht in der Feldverwaltung und in der Feld-Definition der API (GET /api/v2/field-definitions/{tabelle}, Attribut v1_name).

Installationen mit V1-Namen

Viele Installationen sind so eingerichtet, dass der V1-Code selbst der api_name ist — dort trägt schon die normale Antwort die Codes und der Schalter oben ändert nichts. Welche Variante vorliegt, zeigt GET /api/v2/field-definitions/{tabelle}: dort stehen api_name und v1_name nebeneinander.