Skip to main content

Meta Objekt

Zusätzlich zu einem passenden Auth-Token wird eine meta Objekt für alle authentifzierten Anfragen benötigt. Dieses Objekt identifiziert die Abfrage und übergibt einen Kontext für den Aufruf.

So geben gemeinde, und objekt an, für welche Gemeinde sowie welchen Vermieter und Objekt der Gemeinde der Aufruf verwendet wird.

Das Meta Objekt kann nicht alleine übergeben werden. Es gehört immer zu einem weiteren Aufruf (siehe entspr. Kapitel)

Parameter

Feld Datentyp benötigt Beschreibung  
gemeinde int true Die ID der zu buchenden Gemeinde  
objekt int true Die ID des zu buchenden Vermieters  
requestId string (nur wenn idempotent= true) Eine optionale Referenz zur Buchung Rückgabe: die übergebene Zeichekette, oder falls nicht übergeben, eine zufällig generierte Zeichenkette
idempotent bool false Anfrage auf Eindeutigkeit prüfen  

Eindeutige Anfragen (Idempotenz)

Um Mehrfachbuchungen bei Verbindungsabbrüchen oder anderen Fehlern zu unterbinden bietet die Schnittstelle die Möglichkeit, das feld idempotent im Meta-Objekt zu übergeben.

In Verbindung mit der requestId ist es somit möglich, sicherzustellen, dass das  System keine Mehrfachanfragen zulässt.

Der erste Aufruf eines idempotenten Requests wird normal angenommen - jede weitere Anfrage mit der gleichen Request-ID wird abgelehnt, solange das System diese Request-ID speichert.

Gespeicherte Request-IDs verfallen nach 5 Minuten (300 Sekunden). Nach Ablauf kann die gleiche Request-ID wieder verwendet werden. Es ist jedoch immer ratsam eine neue, zufällig generierte Request-ID zu erzeugen.

Die Request-IDs sind immer auf den Benutzer der Anfrage bezogen eindeutig. Somit könnten  user1 und user2 die Request-ID 123-456-789 verwenden, ohne Fehler zu erhalten.

Alle Anfragen die das Meta-Objekt enthalten, unterstützten dieses Merkmal.

Die Request-ID wird erst nach einem erfolgreich durchgeführten Vorgang auf dem Server gespeichert. Bei parallelen Anfragen besteht keine Garantie für Eindeutigkeit.

Vorgehensweise:

  • Generieren Sie  eine eindeutige Request-ID z.B. über eine uuid-Funktion z.B (https://docs.python.org/3/library/uuid.html)
  • Übergeben Sie die Request-ID im Feld requestId
  • Setzen Sie das Merkmal idempotent auf true
{
	"meta": {
		"gemeinde":1,
     	"objekt": 2049,
		"requestId": "123-456-789",
		"idempotent":true
	}
}

Wenn Sie das idempotent Merkmal verwenden, ist die Übergabe des Feldes requestId zwingend notwendig.

 

Beispiele

Request
{
   "meta": {
     "objekt": 806,
     "gemeinde": 1,
     "requestId":"abcdefg"  // In der Antwort wird der gleiche Wert wieder in "requestId" enthalten sein
   },
   //weitere Daten
}
XML
<?xml version="1.0" encoding="utf-8"?>
<meta>
    <vermieter>1</vermieter>
    <gemeinde>1</gemeinde><!-- in diesem Fall wird als requestId eine zufällige Zeichenkette zurückgegeben -->
</meta>
<!-- weitere Daten -->

 

Response

JSON

{
  "meta": {
     "requestId": "66f81f62-0942-11eb-bd68-c04a00212a69",
     "timestamp": "2020-10-08T10:43:56.496102",
     "user": {
            "id": 38,
            "username": "DemoV",
            "alias": "Lisa Mustermann"
        },
        "gemeinde": 1
    }
}

 

Back to top