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 entsteht 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. 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": 0.0,
        "IsActive": true,
        "EntryTypeId": "1bbaef44-9ce9-4cf5-b20b-73056c195f6b"
    },
    "SubscriptionInfo": null,
    "EntryOwner": {
        "Email": "test@gmail.de"
    },
    "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:
    • E-Mail-Adresse des Eintragsbetreibers
  • 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

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. Bilder können optional über die Pictures-Sektion hochgeladen 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.

    Unverbindlichen Beratung anfragen

    Gerne besprechen wir in einem Vorgespräch in ca. 15 Minuten Ihre Portalidee und ob und wie sich diese mit discoverize umsetzen ließe. Entweder per Telefon oder gerne auch in Person bei uns im Büro.



    9-12 Uhr12-15 Uhr15-18 Uhr

      Kontakt zum discoverize Team

      Bei allen Fragen rund Branchenportale, Beratung, Strategie helfen wir gerne weiter.