API Quickstart

Erster Aufruf gegen die go~mus REST-API in fünf Minuten - Auth, whoami, Versionscheck und ein paginierter Index.

Diese Seite bringt du vom Stand „nichts gemacht“ zu „erste API-Antwort gelesen“ in fünf Minuten. Tiefere Zusammenhänge erklären wir in Konzepten und in den Szenarien.

Voraussetzungen

  • Eine go~mus-Instanz, gegen die du sprichst. Beispiele in dieser Doku verwenden demo.gomus.de. Eure echte Instanz folgt dem Muster <instanz>.gomus.<tld>, wobei <tld> je nach Land de, at, ch, be oder lu sein kann.
  • Ein API-Token. Token bekommst du vom go~mus-Support oder aus eurem Backend, falls eingerichtet. Tokens sind kontextsensitiv: Public, User, Reseller. Mehr dazu unter Authentifizierung.
  • curl oder ein HTTP-Tool deiner Wahl.

Schritt 1: Version prüfen

Die aktuelle API-Version steht öffentlich am /api/v4/version-Endpunkt. Ohne Auth.

curl https://demo.gomus.de/api/v4/version

Antwort (gekürzt):

{
  "version": {
    "system": "4.2.15.0",
    "api": "4.5.0",
    "release": "J. Fred Muggs",
    "instance": "demo.gomus.de",
    "time": "2026-05-05T06:32:55+02:00",
    "zone": "Europe/Berlin",
    "currency": "EUR",
    "per_page": 25
  }
}

version.api ist die API-Version (für Feature-Detection auf Client-Seite). per_page ist der Default für paginierte Indexe auf dieser Instanz und kann je Instanz variieren.

Schritt 2: Token testen

curl -H "Authorization: Bearer DEIN_TOKEN" \
  https://demo.gomus.de/api/v4/whoami

Antwort sieht etwa so aus:

{
  "access": "user",
  "museums": []
}

access zeigt deine Rolle. museums: [] heißt: alle Museen der Instanz sind sichtbar. Eine konkrete Liste schränkt ein.

Schritt 3: Paginierter Index

Hol die Liste der Tickets:

curl -H "Authorization: Bearer DEIN_TOKEN" \
  "https://demo.gomus.de/api/v4/tickets?page=1"

Antwort enthält neben den Tickets ein meta-Objekt:

{
  "tickets": [ ... ],
  "meta": {
    "total_count": 42,
    "page": 1,
    "per_page": 25
  }
}

Mit total_count und per_page rechnest du die Anzahl der Seiten aus, ohne raten zu müssen.

Schritt 4: Eine konkrete Ressource holen

Die ID eines Tickets aus dem Index, dann der Detail-Aufruf:

curl -H "Authorization: Bearer DEIN_TOKEN" \
  https://demo.gomus.de/api/v4/tickets/3

Wenn du Daten in mehreren Sprachen brauchst, hängst du ?locale=de an. Das geht für die meisten Endpunkte.

Was als Nächstes

  • Konzepte: die Vokabeln, die du immer wieder siehst (Instance, Quote, Reservation, Order, Pay-By-Link).
  • Szenario: Webseiten-Integration: kompletter Walkthrough für eine Museums-Webseite mit Veranstaltungskalender, Anfragen und Direktbuchungen.
  • Authentifizierung: kontextsensitive Tokens, foreign_id-Pattern, Best Practices.
  • API-Referenz: vollständige Endpoint-Liste in der OpenAPI-Spec deiner Instanz unter https://<instanz>.gomus.<tld>/api-docs/ (Swagger-UI, public). JSON-Spec direkt unter /api-docs/v4/swagger.json für Tooling und SDK-Generierung.

Caching-Hinweis

Stammdaten (Tickets, Events, Tours, Beschreibungen) ändern sich selten. Cache sie tageweise. Verfügbarkeiten und Sitzplätze nicht cachen, die müssen live sein. Implementiere eine Cache-Strategie, bevor du produktiv gehen. Direkt-Live-Traffic vermeiden.