# Meta Objekt

Zusätzlich zu einem passenden Auth-Token wird eine `<span class="n">meta</span>` Objekt für alle authentifzierten Anfragen benötigt. Dieses Objekt identifiziert die Abfrage und übergibt einen Kontext für den Aufruf.

So geben `<span class="n">gemeinde</span>`, und `<span class="n">objekt</span>` an, für welche Gemeinde sowie welchen Vermieter und Objekt der Gemeinde der Aufruf verwendet wird.

<p class="callout info">Das Meta Objekt kann nicht alleine übergeben werden. Es gehört immer zu einem weiteren Aufruf (siehe entspr. Kapitel)</p>

### Parameter

<div id="bkmrk-feld-datentyp-ben%C3%B6ti"><table style="height: 145px; width: 834px;"><thead><tr style="height: 29px;"><th style="height: 29px; width: 98.25px;">Feld</th><th style="height: 29px; width: 75.1833px;">Datentyp</th><th style="height: 29px; width: 142.35px;">benötigt</th><th style="height: 29px; width: 218.533px;">Beschreibung</th><th style="width: 274.683px; height: 29px;"> </th></tr></thead><tbody><tr style="height: 29px;"><td style="height: 29px; width: 98.25px;">gemeinde</td><td style="height: 29px; width: 75.1833px;">int</td><td style="height: 29px; width: 142.35px;">true</td><td style="height: 29px; width: 218.533px;">Die ID der zu buchenden Gemeinde</td><td style="width: 274.683px; height: 29px;"> </td></tr><tr style="height: 29px;"><td style="height: 29px; width: 98.25px;">objekt</td><td style="height: 29px; width: 75.1833px;">int</td><td style="height: 29px; width: 142.35px;">true</td><td style="height: 29px; width: 218.533px;">Die ID des zu buchenden Vermieters</td><td style="width: 274.683px; height: 29px;"> </td></tr><tr style="height: 29px;"><td style="height: 29px; width: 98.25px;">requestId</td><td style="height: 29px; width: 75.1833px;">string</td><td style="height: 29px; width: 142.35px;">(nur wenn `idempotent`= true)</td><td style="height: 29px; width: 218.533px;">Eine optionale Referenz zur Buchung</td><td style="width: 274.683px; height: 29px;">Rückgabe: die übergebene Zeichekette, oder falls nicht übergeben, eine zufällig generierte Zeichenkette</td></tr><tr style="height: 29px;"><td style="width: 98.25px; height: 29px;">idempotent</td><td style="width: 75.1833px; height: 29px;">bool</td><td style="width: 142.35px; height: 29px;">false</td><td style="width: 218.533px; height: 29px;">Anfrage auf Eindeutigkeit prüfen</td><td style="width: 274.683px; height: 29px;"> </td></tr></tbody></table>

</div>### 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.

<p class="callout info">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.</p>

<p class="callout info">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.</p>

<p class="callout info">Alle Anfragen die das Meta-Objekt enthalten, unterstützten dieses Merkmal.</p>

<p class="callout warning">Die Request-ID wird erst nach einem erfolgreich durchgeführten Vorgang auf dem Server gespeichert. Bei parallelen Anfragen besteht keine Garantie für Eindeutigkeit.</p>

**Vorgehensweise:**

- Generieren Sie eine eindeutige Request-ID z.B. über eine uuid-Funktion z.B ([https://docs.python.org/3/library/uuid.html](https://docs.python.org/3/library/uuid.html))
- Übergeben Sie die Request-ID im Feld `requestId`
- Setzen Sie das Merkmal `idempotent` auf `true`

```JSON
{
	"meta": {
		"gemeinde":1,
     	"objekt": 2049,
		"requestId": "123-456-789",
		"idempotent":true
	}
}
```

<p class="callout warning">Wenn Sie das `idempotent` Merkmal verwenden, ist die Übergabe des Feldes `requestId` zwingend notwendig.</p>

#####  

### Beispiele

##### Request

<div id="bkmrk-"></div><div id="bkmrk-json-%7B-%22meta%22%3A-%7B-%22ob"><div><label for="__tab_6_0">JSON</label></div>```json
{<br></br>   "meta": {<br></br>     "objekt": 806,<br></br>     "gemeinde": 1,<br></br>     "requestId":"abcdefg"  // In der Antwort wird der gleiche Wert wieder in "requestId" enthalten sein<br></br>   },<br></br>   //weitere Daten<br></br>}
```

<div>XML</div></div>```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

```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
    }
}
```