Eintrags-API

Die Eintrags-API ist eine REST (RESTful) API, über die die Daten aller Einträge eines Portals abgerufen und potentiell auch geändert werden können. Auch neue Einträge können angelegt werden. Diese API wird langfristig die anderen Speziallösungen ablösen und perspektivisch in 2022 und darüber hinaus auch noch erweitert. Aktuell befindet sich die API im Beta-Status.

Zur Info: dieses Feature entstand im Rahmen von Customizing für einen Kunden und umfasst erstmal im Kern nur die für den Kunden benötigten Features. Unterstützt werden z. B. noch nicht alle möglichen Eigenschaftstypen, sondern die wichtigsten einfachen Eigenschaften wie Texteigenschaften, Links, Ja/Nein Eigenschaften, Mehrfachauswahl und Kategorien. Integrations-Eigenschaften werden auch exportiert, falls in der Eigenschaft Links hinterlegt werden und keine Html/Javascript-Daten für Widgets. Längerfristig wollen wir die API jedoch entsprechend erweitern, so dass darüber Einträge mit allen Eigenschaften genauso angepasst werden können wie über das Eintragsmanagement des Portals selbst.

Aktivieren der API

Die API kann jederzeit durch den Support aktiviert werden. Weitere Einstellmöglichkeiten und Informationen zu Sicherheitseinstellungen werden dann im Portalmanagement unter Einstellungen > API angezeigt.

Datenformat eines Eintrags

Beispiel für JSON-Object eines Eintrags, bei dem nur der Name und die Beschreibung ausgefüllt sind:

{
    "BasicInfo": {
        "Id": 265564,
        "ModifiedDate": "2022-02-23T15:19:19.9506818Z",
        "CreatedDate": "2022-02-04T15:50:01",
        "Url": "http://discoverize/ausflugsziel/test-entry",
        "CompletenessInPercent": 15.5384615384615,
        "TotalScore": 15.5384615384615,
        "NumberOfRatings": 2.0,
        "AverageRating": 4.5,
        "IsActive": true,
        "EntryTypeId": "1bbaef44-9ce9-4cf5-b20b-73056c195f6b"
    },
    "SubscriptionInfo": null,
    "EntryOwner": {
        "Salutation": "Frau",
        "Title": "Dr.",
        "LastName": "Test",
        "FirstName": "Luise",
        "CompanyName": "ABC GmbH",
        "Street": "Musterstraße 42",
        "PostalCode": "12345",
        "Town": "Musterstadt",
        "CountryIso": "DE",
        "Email": "test@gmail.com",
        "Phone": "0049 69 111 22 33",
        "Fax": null
    },
    "Properties": [
        {
            "Name": "Name",
            "Type": "Text",
            "Value": "Test-Entry"
        },
        {
            "Name": "Description",
            "Type": "Text",
            "Value": "This is the description."
        }
    ],
    "Pictures": []
}

BasicInfo:
- Metadaten, z. B.: URL zur Eintragsseite, Erstellungsdatum, Anzahl Bewertungen, …
SubscriptionInfo:
- Informationen zur aktuellen Premiumbuchung (falls vorhanden)
EntryOwner:
- Gibt alle Daten eines Eintrasbetreibers zurück (GET), beim Ändern von Einträgen (PUT, POST) wird jedoch nur die E-Mail-Adresse des Eintragsbetreibers berücksichtigt.
Properties: Liste aller unterstützten Eigenschaften des Eintrags, jeweils in der Form:
- Name: Name der Eigenschaft
  - Das ist immer der zuerst vergebene Name einer Eigenschaft. Auch wenn der Anzeigetext geändert wird, bleibt dieser Name gleich.
  - Das unterscheidet sich vom Export per Excel- oder CSV-Datei, wo immer der aktuelle Anzeigetext als Spaltenüberschrift verwendet wird.
- Type: Typ der Eigenschaft
- Value: aktuell hinterlegter Wert für die Eigenschaft (kann bei bestimmten Eigenschaftstypen komplexeres JSON sein, wird jedoch immer in einen String eingebettet)
- Mehr Informationen gibt es auf der Seite Eintrags-API: Eigenschaften
Pictures: Liste mit Bildern des Eintrags
- Mehr Informationen gibt es auf der Seite Eintrags-API: Bilder

Allgemeine Funktionsweise

Wenn das Feature aktiviert ist, kann über einen abgesicherten API-Endpunkt die Abfrage von außen gestellt werden. Die Eintragsdaten werden im Format JSON geliefert. Die Sicherheitsanforderungen besprechen wir beim Aktivieren des API-Endpunkts.

Abruf aller Daten (GET)

https://PORTAL-DOMÄNE/api/entries/v1

Hier können alle aktiven Einträge als GET-Request abgerufen werden. Je nach Anzahl der Einträge und Eigenschaften im Portal kann die Antwort viele Megabyte groß sein. Im Hintergrund wird diese Antwort einmal täglich erstellt und als Datei zwischengespeichert, da das Erstellen des JSON mit all seinen Informationen bei vielen Einträgen im Portal lange dauern kann. Somit sind die Daten, welche über die API abgefragt werden, maximal 24 Stunden alt. Grundsätzlich werden die gleichen Daten bereitgestellt, die auch über den CSV-Export abgerufen werden können.

Abruf der Daten eines Eintrags (GET)

https://PORTAL-DOMÄNE/api/entries/v1/ID_EINTRAG

Über den gleichen Endpunkt werden bei Angabe einer Eintrags-Id die Daten eines einzelnen Eintrags (aktiv oder inaktiv) zurück geliefert. Dies sind immer aktuelle Daten, entsprechen also dem aktuellen Datenstand eines Eintrags im Portal.

Eintrag editieren (PUT)

https://PORTAL-DOMÄNE/api/entries/v1/ID_EINTRAG

Zum Editieren der Eigenschaften eines Eintrags. Es werden noch nicht alle Eigenschaftstypen unterstützt.

Zum Ändern von Eigenschaften muss das JSON-Objekt nur das Properties-Array enthalten.

Über die Pictures-Sektion können optional neue Bilder importiert werden, vorhandene Bilder angepasst werden (Beschreibung, Reihenfolge etc.) und es können auch Bilder gelöscht werden.

Die anderen Sektionen werden ignoriert, da diese nur lesbare Informationen enthalten, die nicht geändert werden können.

Eintrag neu anlegen (POST)

https://PORTAL-DOMÄNE/api/entries/v1

Hierüber können Einträge neu angelegt werden. Der Eintrag wird dann mit der generierten ID zurückgegeben.

Zum Befüllen von Eigenschaften muss das JSON-Objekt nur das Properties-Array enthalten und den gewünschten Eintragstyp des neuen Eintrags. Die „Name“-Eigenschaft muss in jedem Fall übergeben werden, da ansonsten auch keine URLs für den Eintrag erstellt werden können.

Beispiel für die Mindest-Daten zum Anlegen eines Eintrags (mit Eintragstyp und Name-Eigenschaft):

{ 
    "EntryTypeId": "1bbaef44-9ce9-4cf5-b20b-73056c195f6b", 
    "Properties": [
        {
            "Name": "Name",
            "Type": "Text",
            "Value": "Name of the new entry"
        }
    ]
}

Bilder können optional über die Pictures-Sektion hochgeladen werden. Die Eintragsbetreiberdaten können optional über die EntryOwner-Sektion gesetzt werden. Die anderen Sektionen werden ignoriert, da diese nur lesbare Informationen enthalten, die jedoch nicht geändert werden können.