English Version

Zurück zur Übersicht

API Endpoints: Technik

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

Architektur

Das Plugin nutzt zwei Wege in die API von osTicket:

• Signal-Routen. In bootstrap() hängt sich das Plugin an das Signal api von osTicket, wenn die Einstellung Enable API Endpoints an ist. Der Handler onApiRequest() stellt zwei Routen voran: POST /tickets.(xml|json|email) für die erweiterte Ticket-Erstellung und PATCH/PUT /tickets/{number}.(json|xml) für Updates.
• Eigenständige Endpunkt-Dateien. Alle anderen Endpunkte sind PHP-Dateien aus dem api/-Ordner des Plugins. Beim Aktivieren werden sie nach /api/ kopiert. Sie laden den osTicket-Bootstrap selbst, nutzen das Signal nicht und werden durch Rewrite-Regeln in /api/.htaccess durchgelassen.

graph TD
    A["Client-Anfrage"] --> B["POST /api/tickets.json oder PATCH /api/tickets/:number.json"]
    A --> C["Endpunkt-Dateien in /api/, zum Beispiel tickets-get.php"]
    B --> D["Signal api, onApiRequest"]
    D --> E["ExtendedTicketApiController"]
    C --> F["ApiBootstrap"]
    F --> E
    F --> G["SubticketApiController"]
    E --> H["Services und osTicket-Core"]
    G --> H
    H --> I["Antwort als JSON, XML oder Klartext"]

Ablauf bei einem eigenständigen Endpunkt

sequenceDiagram
    participant C as Client
    participant E as Endpunkt-Datei
    participant B as ApiBootstrap
    participant K as Controller
    participant P as PermissionChecker
    participant S as Service

    C->>E: GET /api/tickets-get.php/781258.json
    E->>B: Pfad zerlegen und Methode prüfen
    E->>K: getTicket(number)
    K->>P: can_read_tickets verlangen
    P-->>K: erlaubt oder 401
    K->>S: TicketService.getTicket
    S-->>K: Ticketdaten
    K-->>B: Array
    B-->>C: JSON oder XML

ApiBootstrap ist die gemeinsame Basis aller Endpunkt-Dateien: Sie zerlegt den Pfad mit einem regulären Ausdruck, prüft die HTTP-Methode (405), liest den JSON-Body und sendet erfolgreiche Antworten und Fehler. Exceptions tragen den HTTP-Statuscode.

Schichten

Verzeichnisstruktur

api-endpoints/
├── api/                          # Endpunkt-Dateien, werden nach /api/ kopiert
│   ├── tickets-get.php
│   ├── tickets-update.php
│   ├── tickets-delete.php
│   ├── tickets-search.php
│   ├── tickets-stats.php
│   ├── tickets-statuses.php
│   ├── tickets-attachment-download.php
│   └── tickets-subtickets-{parent,list,create,unlink}.php
├── assets/
│   └── admin-apikey-extension.js # Admin-Skript, vom Plugin-Code nicht geladen
├── controllers/
├── lib/
│   ├── ApiBootstrap.php
│   ├── XmlHelper.php
│   ├── Enums/
│   └── Services/
├── tests/                        # PHPUnit-Tests (Unit, Integration)
├── docs/
├── class.ApiEndpointsPlugin.php  # Plugin-Klasse ApiEndpointsPlugin
├── config.php                    # Config-Klasse ApiEndpointsConfig
├── plugin.php                    # Plugin-Manifest
├── htaccess.template             # Rewrite-Regeln für /api/.htaccess
└── openapi.yaml                  # OpenAPI-Beschreibung

Datenbank

Das Plugin ergänzt die API-Key-Tabelle von osTicket um sechs Spalten vom Typ TINYINT(1) UNSIGNED NOT NULL DEFAULT 0: can_update_tickets, can_read_tickets, can_search_tickets, can_delete_tickets, can_read_stats und can_manage_subtickets. Die Spalten werden angelegt, wenn sie fehlen, vorhandene Daten bleiben unangetastet. Das Deaktivieren oder Entfernen des Plugins löscht sie nicht.

Gut zu wissen

• Berechtigungsprüfung: Bei den eigenständigen Endpunkten liest PermissionChecker die Spalte des API-Keys. Fehlend oder 0 bedeutet verweigert. Nur can_search_tickets und can_read_stats fallen auf can_read_tickets zurück. Eine fehlgeschlagene Prüfung wirft eine Exception mit Code 401.
• Create-Route: Der Handler von POST /tickets.json validiert die Plugin-Parameter und ruft dann den Controller mit abgeschalteter API-Key-Prüfung auf. Das Plugin selbst prüft auf dieser Route also weder den Key noch can_create_tickets.
• Wildcard-Plugin: Existiert include/plugins/api-key-wildcard/api.wildcard.inc.php, validiert der Controller den API-Key mit dessen WildcardApiController, sonst mit der Standardprüfung von osTicket.
• Erstellen: Das Plugin verbraucht departmentId und parentTicketNumber, entfernt seine eigenen Felder vor der Übergabe an osTicket und setzt Abteilung und Elternticket, nachdem das Ticket existiert.
• Aktualisieren: Die Felder werden nacheinander ohne Transaktion angewendet.
• Fehler: Fehler, die das Plugin in den eigenständigen Endpunkten auslöst, kommen als {"error": true, "message": ...}, die Signal-Routen antworten mit Klartext. Fehler der API-Key-Prüfung haben das Format von osTicket-Core oder API Key Wildcard.

Sicherheit

• Attachment-Zugriff: Der Download-Endpunkt prüft vor dem Ausliefern, dass in der Anhang-Tabelle ein Eintrag mit der angefragten file_id existiert, und lehnt sonst mit 403 ab. Die Prüfung filtert nicht nach dem Typ des Objekts, zu dem der Anhang gehört.
• Berechtigungs-Standard: Alle Berechtigungsspalten starten deaktiviert.
• SQL: Dynamisch gebaute Abfragen casten IDs auf Integer, escapen Werte und prüfen Spaltennamen gegen eine feste Liste.
• XML: Werte werden beim Erzeugen von XML escaped.
• JSON-Eingabe: Die Verschachtelungstiefe des gelesenen Bodys ist begrenzt.

Tests

Die Tests laufen mit PHPUnit:

composer install
composer test              # alle Tests
composer test:unit         # nur Unit-Tests
composer test:integration  # nur Integrationstests
composer test:coverage     # HTML-Coverage-Report

OpenAPI

Das Repository enthält openapi.yaml mit einer OpenAPI-Beschreibung der Endpunkte. Wo beide abweichen, gilt diese Dokumentation als Referenz.