Technische Daten

Die easyfeedback-Schnittstelle ist eine API auf REST-Basis. Über die Schnittstelle werden grundlegende Daten von easyfeedback zur Verfügung gestellt. Die hier beschriebene Dokumentation bezieht sich auf die V2 der easyfeedback API.

Anmeldung & Authentifizierung

Die Anmeldung an die API erfolgt über die folgende Methode. Die dafür benötigten Credentials (API-Zugang) kannst du dir in deinem easyfeedback Account erstellen. Klicke dazu in deinem easyfeedback Account oben rechts auf „Account > Accountdaten“ und öffne den Tab „Integration“. Hier kannst du dir deine Credentials erstellen und verwalten.

Bitte beachten: Deine persönlichen Credentials geben dir, gemäß der Benutzerverwaltung, nur Zugriff auf die Umfragedaten, die deiner Benutzergruppe zugeordnet sind.

Für die Anmeldung steht nur der Grant Type „Client Credentials“ zur Verfügung.

<?php

// Authentifizierung - Acces Token ($accessToken) abrufen
// getAccessToken.php
// v1.0.1

// https://app.easy-feedback.com > Account > Accountdaten > Integration > Neuen Client Zugang einrichten

// Client-ID hier eintragen
$clientId = 'YOUR_CLIENTID';
// Sicherheits-ID hier eintragen
$clientSecret = 'YOUR_CLIENTSECRET';

$accessTokenUrl = 'https://app.easy-feedback.com/api/v2/token';

// Daten für die Anfrage zusammenstellen
$data = array(
    'grant_type' => 'client_credentials',
    'client_id' => $clientId,
    'client_secret' => $clientSecret,
);

// cURL-Optionen konfigurieren
$ch = curl_init($accessTokenUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis verarbeiten (z.B., das Access Token extrahieren)
$result = json_decode($response, true);

if ($result && isset($result['access_token'])) {
    $accessToken = $result['access_token'];
    echo 'Access Token: ' . $accessToken;
} else {
    echo 'Fehler beim Abrufen des Access Tokens.';
}
echo '<br><br>JSON-Antwort: <pre>' . json_encode($result, JSON_PRETTY_PRINT)."</pre>";

// cURL-Verbindung schließen
curl_close($ch);

?>

Beschränkungen

Der Zugriff auf die API ist auf insgesamt 60 Anfragen pro Minute pro Methode beschränkt.

Abfragen können mit den Parametern „page“ und „limit“ eingeschränkt werden, um Obergrenzen bei Abfragen zu umgehen. Dabei werden die Gesamtergebnisse in mehrere Seiten mit der bei „limit“ angegebenen Zahl an Ergebnissen zurückgeliefert.

Mit „page = n“ erhält man die jeweilige Seite der Ergebnisse.

Verwendung von Parametern

Die Parameter werden als GET-Parameter URL-codiert an die URL angehängt.

Beispiel:
Per „/api/v2/members“ sollen alle Teilnehmer der Umfrage 42 aufgerufen werden. Da die Umfrage sehr viele Teilnehmer hat, wird die Paginierung verwendet, um von Seite 1 maximal 100 Ergebnisse zu erhalten. Der Parameter-Teil der URL beginnt mit einem Fragezeichen, gefolgt von den Parametern mit Name und Wert. Die einzelnen Parameter werden mit einem „Kaufmännischen Und“ (&) verbunden.

Parameter:
surveyid=42
page=1
limit=100

Ergibt als Abfrage-URL:
https://app.easy-feedback.com/api/v2/members/?surveyid=42&page=1&limit=100

Datenformat

Das Rückgabeformat ist jeweils JSON. Dabei bestehen die Ergebnisse aus zwei Objekten:

1. meta – Beinhaltet Meta-Informationen über die Daten sowie die Abfrage
2. results – Beinhaltet die eigentlichen Daten als Array aus Objekten

Datumsangaben sind im ATOM-Format gehalten. Beispiel: 2003-12-13T18:30:02.25+01:00

Für das „meta“-Objekt gibt es die folgenden Rückgabewerte:

Beispiel eines Ergebnisses mit Paginierung:

{
  "meta": {
    "count": 1,
    "page": 1,
    "limit": 20,
    "total": 1,
    "requestedAt": "2023-09-07T08:33:40+00:00"
  },
  "results": [
    {
      "Id": 14079, 
      "Type": "String",
      "MemberId": 32103,
      "QuestionId": 959,
      "AnswerId": 40,
      "LevelId": 0,
      "Text": "th.jpeg"
    }
  ]
}