Deutsche Version

Back to overview

API Endpoints: Technical Details

This documentation always describes the latest published version.

Architecture

The plugin uses two paths into osTicket's API:

• Signal routes. In bootstrap(), the plugin connects to osTicket's api signal when the setting Enable API Endpoints is on. The handler onApiRequest() prepends two routes: POST /tickets.(xml|json|email) for extended ticket creation and PATCH/PUT /tickets/{number}.(json|xml) for updates.
• Standalone endpoint files. All other endpoints are PHP files from the plugin's api/ folder. On enabling, they are copied to /api/. They load osTicket's bootstrap themselves, do not use the signal and are let through by rewrite rules in /api/.htaccess.

graph TD
    A["Client request"] --> B["POST /api/tickets.json or PATCH /api/tickets/:number.json"]
    A --> C["Endpoint files in /api/, for example tickets-get.php"]
    B --> D["Signal api, onApiRequest"]
    D --> E["ExtendedTicketApiController"]
    C --> F["ApiBootstrap"]
    F --> E
    F --> G["SubticketApiController"]
    E --> H["Services and osTicket core"]
    G --> H
    H --> I["JSON, XML or plain text response"]

Request Flow of a Standalone Endpoint

sequenceDiagram
    participant C as Client
    participant E as Endpoint file
    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: parse path and check method
    E->>K: getTicket(number)
    K->>P: require can_read_tickets
    P-->>K: allowed or 401
    K->>S: TicketService.getTicket
    S-->>K: ticket data
    K-->>B: array
    B-->>C: JSON or XML

ApiBootstrap is the shared base of all endpoint files: it parses the path with a regular expression, checks the HTTP method (405), parses the JSON body and sends successful responses and errors. Exceptions carry the HTTP status code.

Layers

Directory Structure

api-endpoints/
├── api/                          # Endpoint files, copied to /api/
│   ├── 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 script, not loaded by the plugin code
├── controllers/
├── lib/
│   ├── ApiBootstrap.php
│   ├── XmlHelper.php
│   ├── Enums/
│   └── Services/
├── tests/                        # PHPUnit tests (Unit, Integration)
├── docs/
├── class.ApiEndpointsPlugin.php  # Plugin class ApiEndpointsPlugin
├── config.php                    # Config class ApiEndpointsConfig
├── plugin.php                    # Plugin manifest
├── htaccess.template             # Rewrite rules for /api/.htaccess
└── openapi.yaml                  # OpenAPI description

Database

The plugin adds six columns of type TINYINT(1) UNSIGNED NOT NULL DEFAULT 0 to osTicket's API key table: can_update_tickets, can_read_tickets, can_search_tickets, can_delete_tickets, can_read_stats and can_manage_subtickets. The columns are created if they are missing, existing data is not touched. Disabling or removing the plugin does not drop them.

Behaviour Worth Knowing

• Permission check: For the standalone endpoints, PermissionChecker reads the column of the API key. Missing or 0 means denied. Only can_search_tickets and can_read_stats fall back to can_read_tickets. A failed check throws an exception with code 401.
• Create route: The handler of POST /tickets.json validates the plugin parameters and then calls the controller with the API key check switched off. The plugin itself therefore does not check the key or can_create_tickets on this route.
• Wildcard plugin: If include/plugins/api-key-wildcard/api.wildcard.inc.php exists, the controller validates the API key with its WildcardApiController, otherwise with osTicket's standard check.
• Creation: The plugin consumes departmentId and parentTicketNumber, removes its own fields before passing the data to osTicket and applies department and parent after the ticket exists.
• Update: Fields are applied one after another without a transaction.
• Errors: Errors the plugin raises in the standalone endpoints are answered as {"error": true, "message": ...}, the signal routes answer with plain text. Errors of the API key check use the format of osTicket core or API Key Wildcard.

Security

• Attachment access: The download endpoint checks that a row with the requested file_id exists in the attachment table before serving the file, and rejects it with 403 otherwise. The check does not filter by the type of the object the attachment belongs to.
• Permission default: All permission columns start disabled.
• SQL: Dynamically built queries cast IDs to integers, escape values and check column names against a fixed list.
• XML: Values are escaped when XML is generated.
• JSON input: The nesting depth of the parsed body is limited.

Tests

The tests run with PHPUnit:

composer install
composer test              # all tests
composer test:unit         # unit tests only
composer test:integration  # integration tests only
composer test:coverage     # HTML coverage report

OpenAPI

The repository contains openapi.yaml with an OpenAPI description of the endpoints. This documentation is the reference where the two differ.