REST API Route /api/v1/maintenance - Rückgabewert falsch (Object statt Array)

    Ich baue aktuell einen Prometheus Exporter basierend auf der neuen REST API und dabei ist mir aufgefallen, dass der Rückgabewert vom /api/v1/maintenance Endpunkt, nicht mit dessen Doku dem Beispiel-Schema (und auch nicht mit dem bereitgestellten OpenAPI Spec) übereinstimmt.

    Zurückkommen soll laut Doku ein Array in der Form:

    Code
    [
  {
    "startAt": "2022-03-10T16:15:50Z",
    "finishAt": "2022-03-10T16:15:50Z"
  }
]

    Es kommt aber zurück:

    Code
    {
  "finishAt": null,
  "startAt": null
}

    Ich kann mir vorstellen, dass das der Standardwert sein soll, wenn aktuell keine Wartung angekündigt ist. Leider ist dies dennoch unschön, da Tools, welche das OpenAPI Spec der REST API einlesen, nicht damit klarkommen, wenn auf einmal ein Object statt eines Arrays zurückgegeben wird. Nachvollziehbarer wäre somit:

    Code
    [
  {
    "startAt": null,
    "finishAt": null
  }
]

    Falls die Rückgabe in Form eines einzelnen Object beabsichtigt sein sollte, würde mich interessieren, warum dies so (konträr dem bereitgestellten OpenAPI Spec) gemacht worden ist.

    Einmal editiert, zuletzt von CodeHat (28. Januar 2026 um 22:00) aus folgendem Grund: Doku -> Beispiel-Schema

    Vermutlich "nur" ein Bug.
    Wenn ich es richtig gesehen habe, ist in der OAS auch nicht definiert, dass null als Wert für die beiden Properties erlaubt ist. Das dürfte so dann also auch nicht zurückgegeben werden, sondern es müsste immer ein Timestamp drinstehen.

    [Suche] RS Piccolo gesucht

    Einmal editiert, zuletzt von terence (28. Januar 2026 um 21:08)

    Zitat von terence

    Wenn ich es richtig gesehen habe, ist in der OAS auch nicht definiert, dass null als Wert für die beiden Properties erlaubt ist. Das dürfte so dann also auch nicht zurückgegeben werden, sondern es müsste immer ein Timestamp drinstehen.

    Guter Hinweis. Wenn dem so ist, dann sollte entsprechend - bei keiner angekündigten Wartung - ein leeres Array zurückgegeben werden. Das wäre zumindest intuitiver.

    Laut Wiki soll es aktuell keine breaking changes mehr geben. Ist die Frage, ob das auch für Bugfixes gilt?

    Wo findet man eigentlich die von Dir erwähnte Doku? Ich habe bisher nur die OAS gesehen und da steht bei den Operationen nicht viel an Beschreibung drin.

    Hallo CodeHat

    ich melde mich mit Neuigkeiten dazu! :)

    Das zuständige Team hat sich eure Hinweise genauer angesehen.
    Die OpenAPI Spec für den Endpoint GET /api/v1/maintenance war falsch. Es wird kein Array vom Schema Maintenance zurückgegeben. Dies wurde nun behoben, also sollte alles wie gewünscht funktionieren.

    Vielen Dank nochmals und einen schönen Tag!

    Liebe Grüße

    Sarah & das netcup-Team