English Version

Zurück zur Übersicht

API Endpoints: Installation

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Anforderungen

Das Plugin hat keine Laufzeit-Abhängigkeiten, Composer ist auf dem Server nicht nötig.

Schritt 1: Plugin-Dateien installieren

ZIP-Download

1. Lade das aktuelle Release von Releases herunter
2. Entpacke die ZIP-Datei
3. Lade den Ordner api-endpoints nach /include/plugins/ auf deinem osTicket-Server hoch

Git Clone

cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-endpoints.git api-endpoints

Der Ordner muss api-endpoints heißen, der endgültige Pfad ist also /path/to/osticket/include/plugins/api-endpoints/. Die ausgerollten Endpunkt-Dateien laden das Plugin genau von diesem Pfad. Bei einem anderen Ordnernamen scheitern sie mit 500 (API Endpoints Plugin not properly installed).

Schritt 2: Plugin aktivieren

1. Melde dich im osTicket-Admin Panel an
2. Öffne Verwalten → Plugins
3. Installiere API Endpoints, falls es noch nicht installiert ist, und aktiviere es

Beim Aktivieren führt das Plugin Folgendes aus:

• legt seine einzige Plugin-Instanz an
• entfernt tickets-*.php-Dateien und seinen Rewrite-Block aus einer früheren Installation
• ergänzt die Berechtigungsspalten can_update_tickets, can_read_tickets, can_search_tickets, can_delete_tickets, can_read_stats und can_manage_subtickets in der API-Key-Tabelle, alle standardmäßig deaktiviert
• kopiert die Dateien aus dem api/-Ordner des Plugins in den Ordner /api/ deiner osTicket-Installation
• fügt seine Rewrite-Regeln in /api/.htaccess ein
• speichert die installierte Version

Ändert sich die Plugin-Version nach einem Update, werden Spalten, Dateien und Regeln beim nächsten Request automatisch neu ausgerollt.

Das Plugin patcht keine osTicket-Core-Datei. Es legt aber Dateien in /api/ ab, Regeln in /api/.htaccess und Spalten in der API-Key-Tabelle.

Schritt 3: Webserver

Apache (automatisch)

osTicket liefert /api/.htaccess mit. Das Plugin fügt dort die Regeln aus seiner htaccess.template ein, nach der Wildcard-Regel des Plugins API Key Wildcard, falls vorhanden, sonst vor der Standard-API-Regel. Jede Regel lässt eine Endpunkt-Datei direkt durch, zum Beispiel:

RewriteRule ^tickets-get\.php/ - [L]
RewriteRule ^tickets-update\.php/ - [L]
RewriteRule ^tickets-search\.php.*$ - [L]

Existiert /api/.htaccess nicht oder wird keine Einfügestelle gefunden, gibt enable() des Plugins eine Warnmeldung zurück, und du musst die Regeln aus htaccess.template selbst ergänzen. Das Verzeichnis muss .htaccess-Overrides erlauben (AllowOverride).

NGINX (manuell)

Das Plugin ändert die NGINX-Konfiguration nicht. Acht Endpunkt-Dateien erhalten ihren Parameter als PATH_INFO: get, update, delete, attachment-download und alle vier Subticket-Endpunkte. Ergänze das in deinem Server-Block und passe den PHP-FPM-Socket an:

# Endpunkte mit PATH_INFO, zum Beispiel /api/tickets-get.php/123456.json
location ~ ^/api/tickets-(?:get|update|delete|attachment-download|subtickets-(?:parent|list|create|unlink))\.php/ {
    fastcgi_split_path_info ^(/api/tickets-[a-z-]+\.php)(/.+)$;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
}

# Endpunkte ohne PATH_INFO, zum Beispiel /api/tickets-search.php?query=test
location ~ ^/api/tickets-(?:search|stats|statuses)\.php$ {
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
}

sudo nginx -t
sudo systemctl reload nginx

Schritt 4: Prüfen

Ein API-Key mit der Berechtigung can_read_stats oder can_read_tickets muss die Statusliste bekommen:

curl "https://your-domain.com/api/tickets-statuses.php" \
  -H "X-API-Key: YOUR_API_KEY"

404 heißt, der Webserver reicht die Datei nicht durch, siehe Fehlerbehebung. 401 heißt, dem Key fehlt die Berechtigung, siehe Konfiguration.

Update

Ersetze den Inhalt des Ordners api-endpoints durch die neue Version. Beim nächsten Request nach dem Versionswechsel aktualisiert das Plugin die Spalten, kopiert die Endpunkt-Dateien erneut und ersetzt seinen Block in /api/.htaccess.

Deaktivieren und Entfernen

Das Deaktivieren des Plugins im Admin Panel ändert nichts in /api/. Die ausgerollten Endpunkt-Dateien bleiben erreichbar und sind weiterhin durch die API-Key-Berechtigungen geschützt. Nur die beiden Routen POST /api/tickets.json und PATCH /api/tickets/{number}.json werden nicht mehr erweitert.

So entfernst du das Plugin vollständig:

1. Deaktiviere das Plugin und entferne es unter Verwalten → Plugins aus der Liste
2. Lösche den Plugin-Ordner /include/plugins/api-endpoints/
3. Lösche die Dateien tickets-*.php aus /api/
4. Entferne den Block, der mit API Endpoints Plugin - Apache Rewrite Rules beginnt, aus /api/.htaccess, den Rest der Datei lässt du stehen
5. Optional: Entferne die sechs Berechtigungsspalten aus der API-Key-Tabelle

Lösche nicht die /api/.htaccess selbst, osTicket braucht sie. Tickets und Anhänge sind vom Entfernen des Plugins nicht betroffen.