Grundlagen der ProSonata API

Die ProSonata API ist ein RESTful Webservice, bei dem jede Ressource über eine eindeutige URI angesprochen wird.
Die HTTP-Methoden bestimmen dabei, welche Operationen mit einer Ressource ausgeführt werden:

  • GET: Ressource lesen
  • POST: Ressource erstellen
  • PUT: Ressource bearbeiten
  • DELETE: Ressource löschen (nur für einzelne Ressourcen verfügbar)

Sicherheit

Der Zugriff auf die ProSonata API kann und sollte immer verschlüsselt über eine https-Verbindung erfolgen. So ist sichergestellt, dass keine Daten und insbesondere der API-Key im Klartext übertragen und mitgelesen werden können.

Zugriff auf die API

Der Zugriff auf die ProSonata API erfolgt über die URL

https://{subdomain}.prosonata.software/api/v1/{ressource}[/{id}]
Parameter Bedeutung
{subdomain} die Subdomain des ProSonata Accounts
{ressource} die Ressource, auf die zugegriffen werden soll (Aufruf ohne /{id} für Listen (GET) und Anlegen einer neuen Ressource (POST))
{id} optionale ID für Abfrage und Bearbeitung einer konkreten Ressource (für GET, PUT, DELETE)

 

Datenformat

Die ProSonata API nutzt als Datenformat für schreibende und lesende Requests das JSON-Format. Der Zeichensatz ist immer UTF-8.

JSONP wird ebenfalls unterstützt. Dafür muss der Parameter jsonp angegeben werden, welcher optional den Namen der Callback-Funktion enthält. Die Standard-Callback-Funktion lautet callback.

https://{subdomain}.prosonata.software/api/v1/{ressource}?jsonp[=callback]

Authentifizierung

Die Authentifizierung geschieht über die vorhandenen ProSonata Benutzer. Benutzer der Rechtestufe »Administrator« können im Bereich > Benutzer einzelnen Mitarbeitern den Zugriff freischalten. Anschließend muss jeweils ein persönlicher API-Key generiert werden. Dieser Key ist für jeden Zugriff auf die API zwingend erforderlich, weil API-Zugriffe zustandslos sind – es werden keine Sitzungen/Sessions gespeichert.

Bitte kopieren bzw. notieren Sie sich den generierten API-Key – dieser wird als Hash in der Datenbank gespeichert und kann nachträglich in ProSonata nicht mehr erneut angezeigt werden! Sie können aber bei Bedarf einen neuen Key generieren. Für den Zugriff auf die einzelnen Ressourcen gelten die Rechte, die dem jeweiligen Benutzer über die Benutzergruppe zugewiesen wurden. So kann zum Beispiel nur die Benutzergruppe »Administrator« auf die Benutzer des Systems (Ressource users) zugreifen.

Der API-Schlüssel kann auf zwei Arten übermittelt werden. Per GET-Parameter

https://{subdomain}.prosonata.software/api/v1/{ressource}?apiKey=diesIstDerKey

oder im Header der Anfrage

curl -H 'X-API-Key: diesIstDerKey' 
https://{subdomain}.prosonata.software/api/v1/{ressource}

Aufbau der Antworten

Die von der API gelieferten Antworten bestehen aus den Bereichen »meta« für die Metadaten und »data« für die eigentlichen angefragten Daten der Ressource.

{
  "meta": {
    "status": 200,
    "perPage": 100,
    "page": 1,
    "totalCount": 7,
    "apiLimitRemaining": 498,
    "apiLimitReset": 612
  }
  "data": [
    {
      "userID": 1,
      "username": "Max",
      "userFirstName": "Max",
      "userLastName": "Mustermann",
      "email": "max@mustersite.de",
      "userPhone": "069 12345678"
    },
    …
  ]
}

Die Metadaten beinhalten immer nochmals den HTTP-Statuscode. Ressourcenlisten bieten weitergehende Informationen, wie die ausgegebenen Ergebnisse pro Seite (perPage), die Seitenzahl (page) und die Gesamtanzahl der Ergebnisse (totalCount) der Anfrage.

Der Datenteil listet die Felder mit den jeweiligen Inhalten auf.

Zugriffsbegrenzung

Die Anzahl der API-Aufrufe ist begrenzt. Die Begrenzung bezieht sich immer auf Zeitintervalle von 15 Minuten. Wird ein neues Zeitintervall erreicht, steht ein neues Kontingent zur Verfügung. Nicht verbrauchte Aufrufe können nicht angespart und übertragen werden. Das Kontingent richtet sich nach dem gebuchten ProSonata Paket und ist aktuell wie folgt gesetzt:

Paket Limit pro 15 Min.
ProSonata 1 50
ProSonata 3 100
ProSonata 5 200
ProSonata 10 300
ProSonata 20 500

Jeder Aufruf liefert in den Metadaten zwei Felder zum aktuellen Limit mit:

apiLimitRemaining: die Anzahl der noch zur Verfügung stehenden Aufrufe im Zeitintervall
apiLimitReset: Zeitpunkt in Sekunden, ab dem ein neues Zeitintervall startet

Wird innerhalb eines Intervalls die maximale Anzahl an Aufrufen überschritten, wird der HTTP-Fehlercode 429 zurückgeliefert. Die Fehlermeldung gibt Auskunft darüber, ab wann (in Sekunden) erneut auf die API zugegriffen werden kann.

Sollten die zur Verfügung stehenden Anfragen pro Zeitintervall nicht ausreichen, kontaktieren Sie uns bitte. Wir finden in diesem Fall sicher eine Lösung.

Paginierung

Beim lesenden Zugriff (GET) kann die Anzahl der Datensätze per Request über den Parameter perPage angegeben werden. Die einzelnen Seiten können mit dem Parameter page abgefragt werden:

https://{subdomain}.prosonata.software/api/v1/{ressource}?perPage=100&page=2

Standardmäßig werden 100 Datensätze pro Seite (perPage) ausgegeben. Maximal können 1000 Datensätze zurückgegeben werden.

Filterung/Suche

Beim lesenden Zugriff (GET) können gezielt einzelne Felder/Parameter für eine Suche bzw. Filterung genutzt werden. Die zur Verfügung stehenden Parameter sind bei den einzelnen Ressourcen aufgelistet.

Beispiel: Suche nach dem Benutzer mit dem Benutzernamen »Max«:

https://{subdomain}.prosonata.software/api/v1/users?username=Max

Sortierung

Über den optionalen Parameter orderBy kann beim lesenden Zugriff (GET) eine Sortierreihenfolge vorgegeben werden. Eine Sortierung besteht aus dem Namen des Feldes und der Sortierrichtung (analog dem SQL Befehl: ASC für aufstiegende bzw. DESC für absteigende Sortierung). Wird keine Sortierrichtung angegeben, wird aufsteigend ASC sortiert.

Es können mehrere Sortierreihenfolgen berücksichtigt werden, indem diese kommasepariert in der Anfrage mitgegeben werden.

Beispiel: Auflistung der Benutzer nach Benutzername in umgekehrter Reihenfolge:

https://{subdomain}.prosonata.software/api/v1/users?orderBy=username+DESC

Daten schreiben, bearbeiten und löschen

Mit den HTTP-Methoden POST, PUT und DELETE werden Daten geschrieben bzw. bearbeitet und gelöscht.

Da für diesen Zugriff auch das JSON-Format gilt, sollte im Header des Requests der Datentyp »Content-Type: application/json« vorhanden sein:

Beispiel: Erzeugen eines neuen Projekts per POST-Request (hier ohne Body mit dem JSON Datenteil):

curl -v -X POST
-H 'X-API-Key: diesIstDerKey'
-H 'Content-Type: application/json'
https://{subdomain}.prosonata.software/api/v1/projects

Der Request erzeugt ein neues Projekt – der Body muss selbstverständlich die je nach Ressource notwendigen Daten im JSON-Format enthalten. Als Antwort kommt der Status 201 Created und die Antwort enthält im Body nochmals das komplette neue Objekt.

Eine bereits vorhandene Ressource (hier Projekt mit der ID 12) wird per PUT-Request bearbeitet (hier ohne Body mit dem JSON Datenteil):

curl -v -X PUT
-H 'X-API-Key: diesIstDerKey'
-H 'Content-Type: application/json'
https://{subdomain}.prosonata.software/api/v1/projects/12

Bei erfolgreicher Bearbeitung kommt als Antwort der Status 200 OK zurück und die Antwort enthält im Body nochmals das komplette Objekt. Bei einem PUT müssen nicht zwingend alle Parameter im Body übertragen werden – auf diesem Weg können auch nur einzelne Parameter einer Ressource geändert werden.

Eine Ressource (hier Projekzeit mit der ID 16) wird per DELETE-Request gelöscht:

curl -v -X DELETE
-H 'X-API-Key: diesIstDerKey'
https://{subdomain}.prosonata.software/api/v1/projecttimes/16

Weitere Daten sind im Header oder Body beim Löschen nicht notwendig. Bei erfolgreicher Löschung kommt als Antwort der Status 200 OK zurück.

Fehler

Treten Fehler bei der Bearbeitung eines Requests auf, wird mit einem passenden HTTP-Statuscode geantwortet. Ebenso sind im Body nochmals Metadaten im JSON-Format enthalten, die neben dem Status ggf. auch eine ergänzende message enthalten, die bei der Fehlersuche hilfreich sein sollte.

{
  "meta": {
    "status": 404,
    "message": "Data not found.",
    "requestUserID": 1,
    "usergroupName": "Administrator",
    "apiLimitRemaining": 493,
    "apiLimitReset": 583
  },
  "data": [
  ]
}