Heyform-API-Integration: Formulardaten einfach per REST-API abrufen Bild von Marco Griep - Erstellt mit Canva

Heyform-API-Integration: Formulardaten einfach per REST-API abrufen

Veröffentlicht:

Heyforms ist eine beliebte Formular-Software, die es Nutzern ermöglicht, Umfragen, Kontaktformulare und mehr zu erstellen. Allerdings bietet Heyforms standardmäßig nur Webhooks an, um auf eingehende Formulardaten zuzugreifen. Für viele Anwendungsfälle ist dies jedoch nicht ausreichend, insbesondere wenn Entwickler oder Administratoren die Daten flexibel und in Echtzeit abrufen möchten.

Genau hier setzt das Heyform-API-Integration-Projekt an. Mein Open-Source-Projekt bietet eine REST-API, die es ermöglicht, Formulardaten direkt aus der Heyform-Datenbank (MongoDB) abzurufen – ohne sich ausschließlich auf Webhooks verlassen zu müssen. In diesem Blogbeitrag stellen wir die Funktionsweise, die Vorteile und die Nutzung der API vor.

Was bietet die Heyform-API-Integration?

Das Projekt wurde entwickelt, um den Zugriff auf Heyform-Daten zu vereinfachen und flexibler zu gestalten. Es basiert auf Flask und MongoDB und bietet folgende Features:

Abruf aller Formular-Einreichungen

  • Mit optionalen Parametern wie limit und Sortierung nach Erstellungsdatum.
  • Perfekt für die Analyse der neuesten Einreichungen.

Filterung nach Formular-ID

  • Ermöglicht den gezielten Abruf von Einreichungen für ein bestimmtes Formular.

Datenformatierung

  • Antworten werden benutzerfreundlich formatiert, z. B. durch die Zuordnung von Antworten zu ihren Labels bei Mehrfachauswahl-Fragen.

Einfache Integration

  • Die API ist leicht einzurichten und kann in bestehende Systeme integriert werden.

Vorteile der API

Die Heyform-API-Integration bietet zahlreiche Vorteile für Administratoren und Entwickler:

  • Flexibilität: Im Gegensatz zu Webhooks können Daten jederzeit und gezielt abgerufen werden. Auch in der Vergangenheit oder per Cronjob für Reporting
  • Echtzeit-Zugriff: Formulardaten stehen sofort zur Verfügung, ohne auf Webhook-Trigger warten zu müssen.
  • Benutzerfreundliche Formatierung: Die API liefert die Daten in einem klar strukturierten JSON-Format, das leicht weiterverarbeitet werden kann.
  • Open Source: Das Projekt ist unter der MIT-Lizenz lizenziert und kann frei genutzt, weiterentwickelt und geforkt werden.

Installation und Einrichtung

Die Einrichtung der API ist einfach und erfordert nur wenige Schritte:

Voraussetzungen

  • Python 3.x
  • MongoDB (entweder lokal oder über eine Verbindungszeichenfolge)
  • Die Python-Pakete flask, flask_pymongo und bson (können über pip installiert werden)

Installation (manuell)

  1. Repository klonen:
git clone <repository_url>
cd <repository_directory>
  1. Python-Pakete installieren:
git clone <repository_url>
cd <repository_directory>
  1. MongoDB-Verbindung konfigurieren:

Setzen Sie die folgenden Umgebungsvariablen:

export MONGO_DB_HOST="localhost"
export MONGO_DB_PORT="27017"
export MONGO_DB_NAME="heyform"
export MONGO_DB_USER="your_user"
export MONGO_DB_PASS="your_password"

Alternativ können Sie eine MongoDB-Verbindungszeichenfolge (MONGO_DB_CONNECTION_STRING) verwenden.

  1. API starten:
python app.py

Installation mit Docker und Docker Compose

Die Heyform-API-Integration bietet nicht nur eine flexible Möglichkeit, Formulardaten abzurufen, sondern lässt sich auch einfach mit Docker und Docker Compose einrichten. In diesem Abschnitt zeigen wir, wie Sie die API mithilfe einer Docker-Compose-Datei bereitstellen können. Diese Methode ist besonders nützlich, um die gesamte Umgebung – inklusive MongoDB und Redis – schnell und konsistent aufzusetzen.

Docker-Compose-Beispieldatei

Die folgende docker-compose.yml-Datei definiert alle notwendigen Dienste für die Heyform-API-Integration:

services:
  heyform:
    image: heyform/community-edition:latest
    restart: always
    volumes:
      - ./assets:/app/static/upload
    depends_on:
      - mongo
      - keydb
    ports:
      - "80:8000"
    environment:
      APP_HOMEPAGE_URL: "http://www.mypage.com"
      SESSION_KEY: key1
      FORM_ENCRYPTION_KEY: key2
      MONGO_URI: "mongodb://mongo:27017/heyform"
      REDIS_HOST: keydb
      REDIS_PORT: 6379

  mongo:
    image: percona/percona-server-mongodb:4.4
    restart: always
    volumes:
      - ./database:/data/db
    ports:
      - "27017:27017"

  keydb:
    image: eqalpha/keydb:latest
    restart: always
    command: keydb-server --appendonly yes
    volumes:
      - ./keydb:/data

  api:
    build:
      context: app
      dockerfile: Dockerfile
    restart: always
    depends_on:
      - mongo
    environment:
      MONGO_DB_CONNECTION_STRING: "mongodb://mongo:27017/heyform"
    ports:
      - "8001:5000"

Erklärung der Dienste

1. Heyform-Service

  • Image: heyform/community-edition:latest
    Die offizielle Heyform-Community-Edition wird als Basis verwendet.
  • Volumes:
    Das Verzeichnis ./assets wird gemountet, um Uploads persistent zu speichern.
  • Ports:
    Der Service ist über Port 80 erreichbar und leitet Anfragen an Port 8000 weiter.

Umgebungsvariablen:

  • APP_HOMEPAGE_URL: Die URL Ihrer Website.
  • SESSION_KEY und FORM_ENCRYPTION_KEY: Schlüssel für die Sitzungsverwaltung und Verschlüsselung.
  • MONGO_URI: Verbindungs-URI zur MongoDB.
  • REDIS_HOST und REDIS_PORT: Verbindungsdetails für Redis (KeyDB).

2. MongoDB-Service

  • Image: percona/percona-server-mongodb:4.4
    Eine stabile Version von MongoDB wird verwendet.
  • Volumes:
    Das Verzeichnis ./database wird gemountet, um Daten persistent zu speichern.
  • Ports:
    MongoDB ist über Port 27017 erreichbar.

3. KeyDB-Service

  • Image: eqalpha/keydb:latest
    KeyDB ist ein leistungsstarker Redis-Fork, der für die Sitzungsverwaltung verwendet wird.
  • Volumes:
    Das Verzeichnis ./keydb wird gemountet, um Daten persistent zu speichern.
  • Command:
    Der Befehl keydb-server --appendonly yes aktiviert die Persistenz.

4. API-Service

  • Build:
    Der API-Service wird aus dem Verzeichnis app mit einem eigenen Dockerfile gebaut.

Umgebungsvariablen:

  • MONGO_DB_CONNECTION_STRING: Verbindungs-URI zur MongoDB.
  • Ports:
    Die API ist über Port 8001 erreichbar und leitet Anfragen an Port 5000 weiter.

Installation mit Docker Compose

  1. Docker Compose-Datei erstellen:
    Speichern Sie die oben gezeigte docker-compose.yml-Datei in einem Verzeichnis Ihrer Wahl.

Dienste starten:
Führen Sie den folgenden Befehl aus, um alle Dienste zu starten:bashCopydocker-compose up -d

Überprüfen der Dienste:
Stellen Sie sicher, dass alle Dienste korrekt gestartet sind:bashCopydocker-compose ps

  1. API verwenden:
    Die API ist nun unter http://localhost:8001 erreichbar. Sie können die Endpunkte wie im vorherigen Abschnitt beschrieben nutzen.

Vorteile der Docker-Installation

  • Einfache Einrichtung: Mit Docker Compose können Sie die gesamte Umgebung mit einem einzigen Befehl bereitstellen.
  • Isolation: Jeder Dienst läuft in einem separaten Container, was die Stabilität und Sicherheit erhöht.
  • Portabilität: Die Docker-Compose-Datei kann leicht auf anderen Systemen verwendet werden.
  • Persistenz: Durch die Verwendung von Volumes bleiben Daten auch nach dem Neustart der Container erhalten.

API-Endpunkte im Überblick

Die API bietet zwei Hauptendpunkte:

Alle Einreichungen abrufen

  • URL: /submissions
  • Methode: GET

Parameter:

  • limit: Anzahl der zurückzugebenden Einreichungen (Standard: 10).

Beispiel:

GET http://localhost:5000/submissions?limit=5

Einreichungen nach Formular-ID abrufen

  • URL: /submissions/<form_id>
  • Methode: GET

Parameter:

  • form_id: Die ID des Formulars.
  • limit: Anzahl der zurückzugebenden Einreichungen (Standard: 10).

Beispiel:

GET http://localhost:5000/submissions/12345?limit=5

Datenformatierung

Die API liefert die Daten in einem benutzerfreundlichen Format:

  • Das Feld createdAt wird als ISO-8601-Datum zurückgegeben.
  • Antworten werden als Frage-Antwort-Paare formatiert.
  • Bei Mehrfachauswahl-Fragen werden die Antworten ihren Labels zugeordnet.
{
  "question": "What is your favorite color?",
  "answer": ["Red", "Blue"]
}

Die Heyform-API-Integration ist ein leistungsstarkes Tool für alle, die Formulardaten flexibel und effizient nutzen möchten. Durch die Bereitstellung einer REST-API wird der Zugriff auf Heyform-Daten erheblich vereinfacht, und die benutzerfreundliche Formatierung erleichtert die Weiterverarbeitung.

Da das Projekt Open Source ist, laden wir Entwickler und Administratoren ein, es zu nutzen, weiterzuentwickeln und zu forken. Gemeinsam können wir die Integration noch besser machen!

Projekt-Link: GitLab-Repository
Lizenz: MIT

Haben Sie Fragen oder möchten Sie mitwirken? Kontaktieren Sie uns gerne oder erstellen Sie einen Pull Request!