Inhalte erstellen, bearbeiten, verlinken und löschen

Datenschnittstelle für das Erstellen von Inhalten

Mit der dataCycle-API kannst du Inhalte (wie Bilder, Orte, Veranstaltungen) nicht nur abfragen, sondern auch neu anlegen, bearbeiten, verlinken und löschen.
Hier findest du alle wichtigen Schritte und Beispiele.

---

Voraussetzungen

• Es muss eine Konfiguration für eingehende Webhooks hinterlegt sein.
• Das Format der eingehenden Daten wird in der Konfiguration festgelegt (z.B. JSON-LD).
• Die URL für neue Inhalte hat folgendes Format:
  /api/v4/external_sources/CONFIGURATION_ID

---

Einschränkungen

• Das Datenformat entspricht der APIv4-Ausgabe.
• Noch nicht alle Attribute können übergeben werden.
• Manche Attribute heißen beim Erstellen anders als beim Auslesen.

---

Wie übergebe ich Daten?

Du kannst Inhalte als JSON-Body, URL-Encoded Form oder Multipart Form senden.

• Das Feld @type gibt den Typ des Inhalts an (z.B. "dcls:Bild" für ein Bild).
• Die Sprache kannst du mit @context setzen.

---

Beispiel: Einfaches Bild als JSON

{
  "token": "YOUR_ACCESS_TOKEN",
  "@graph": [
    {
      "@type": "dcls:Bild",
      "name": "Name des 1. Bildes"
    },
    {
      "@type": "dcls:Bild",
      "name": "Name des 2. Bildes"
    }
  ]
}

Beispiel: Sprache setzen

{
  "@context": {
    "@language": "de"
  }
}

Beispiel: Übersetzungen für Attribute

{
  "@graph": [
    {
      "@type": "dcls:Bild",
      "name": [
        { "@language": "de", "@value": "Bild 1" },
        { "@language": "en", "@value": "Bild 1 englisch" }
      ]
    }
  ]
}

Inhalte erstellen – Beispiele Beispiel 1: POI (Ort)

{
  "token": "YOUR_ACCESS_TOKEN",
  "@graph": [
    {
      "@id": "test-poi-1",
      "@type": "POI",
      "name": "Test POI",
      "address": {
        "@type": "PostalAddress",
        "url": "https://www.example.com",
        "email": "test@email.at",
        "telephone": "+43 123456789",
        "name": "First Last",
        "streetAddress": "Teststraße 1",
        "addressCountry": "Wakanda"
      },
      "geo": {
        "@type": "GeoCoordinates",
        "latitude": 14.1,
        "longitude": 14.2
      }
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Beispiel 2: Veranstaltung mit Zeitplänen
```bash
{
  "@graph": [
    {
      "@type": "Event",
      "@id": "test-event-1",
      "name": "Test-Event 1",
      "eventSchedule": [
        {
          "@type": "Schedule",
          "startDate": "2024-06-01",
          "startTime": "12:00",
          "scheduleTimezone": "Europe/Vienna",
          "endTime": "14:00"
        },
        {
          "@type": "Schedule",
          "startDate": "2024-06-01",
          "startTime": "12:00",
          "scheduleTimezone": "Europe/Vienna",
          "endTime": "14:00",
          "byDay": ["https://schema.org/Tuesday", "https://schema.org/Thursday"],
          "endDate": "2024-12-31",
          "repeatFrequency": "P1W"
        }
      ]
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Beispiel 3: Bild (verschiedene Upload-Varianten)

Per URL:

{
  "@graph": [
    {
      "@type": "dcls:Bild",
      "name": "Bild 1",
      "asset": {
        "remote_file_url": "http://www.example.com/image.jpg"
      }
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Per Base64:

{
  "@graph": [
    {
      "@type": "dcls:Bild",
      "name": "Bild 2",
      "asset": {
        "base64_file_blob": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
        "name": "image.jpg"
      }
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Inhalte verlinken Vorhandene Inhalte verlinken:

{
  "@graph": [
    {
      "@type": "Event",
      "@id": "test-event-1",
      "image": [
        { "@id": "8adfb8e0-0f8c-4953-9682-04541d389837", "@type": "dcls:Bild" }
      ]
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Neue und vorhandene Inhalte mischen:

{
  "@graph": [
    {
      "@type": "Event",
      "@id": "test-event-1",
      "image": [
        { "@id": "mein-bild-1", "@type": "dcls:Bild", "name": "Bild 1" },
        { "@id": "8adfb8e0-0f8c-4953-9682-04541d389837", "@type": "dcls:Bild" }
      ]
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Inhalte aktualisieren

Um Inhalte zu ändern, gib die @id des Inhalts an. Nicht übergebene Felder bleiben unverändert.

{
  "@graph": [
    {
      "@id": "test-poi-1",
      "@type": "POI",
      "name": "Neuer Name"
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Inhalte löschen

Um Inhalte zu löschen, sende einen DELETE-Request mit der ID:

DELETE /api/v4/external_sources/CONFIGURATION_ID

{
  "@graph": [
    { "@id": "test-poi-1" }
  ]
}

Hinweis: Verlinkte Inhalte werden nicht automatisch gelöscht – das musst du separat machen. Klassifizierungen setzen und löschen

Klassifizierungen sind Kategorien oder Schlagworte, die du angeben kannst. Die ID findest du in der Klassifizierungsverwaltung. Setzen:

{
  "@graph": [
    {
      "@id": "test-poi-1",
      "@type": "POI",
      "dc:classification:tags": ["0741a837-4be6-4c75-85b5-9e00c614cc3e"]
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Löschen:

{
  "@graph": [
    {
      "@id": "test-poi-1",
      "@type": "POI",
      "dc:classification:tags": null
    }
  ],
  "@context": {
    "@language": "de"
  }
}

Antwort und Fehler

Nach dem Erstellen, Aktualisieren oder Löschen bekommst du eine Antwort wie diese:

[
  {
    "success": true,
    "meta": {
      "thing_id": "UUID",
      "external_key": "String",
      "created": [],
      "updated": []
    },
    "error": [],
    "warnings": [],
    "cache_invalidated": 2
  }
]

success: Gibt an, ob alles geklappt hat (true, false oder ‘partial’).

meta: Infos zu den betroffenen Inhalten.

error: Liste der Fehler (falls etwas schiefging).

warnings: Hinweise, die nicht kritisch sind.

cache_invalidated: Wie viele Caches neu geladen werden müssen.

Mit diesen Beispielen kannst du Inhalte einfach erstellen, aktualisieren, verlinken und löschen.m