Public API

BISO stellt eine öffentliche API für diverse Anforderungen bereit. Diese ist NICHT zu verwechseln mit der JSON-API, welches das Frontend benützt: Die JSON-API für das Frontend ist sehr spezifisch und nicht dazu gedacht, als API zu nutzen.

URLs

• [webroot]/backend/api: Dies ist der Einstiegspunkt aller öffentlichen API-Endpunkte. Der zugehörige ApiBaseController.php regelt die gemeinsamen Code-Teile wie z.B Authentifikation.
• doc/api-doc/: Die OpenAPI-Dokumentation zu den öffentlichen Schnittstellen. Diese kann auf Kundensystemen autonom auch unter anderer URL deployt werden.

Routing

Alle API-Routen werden explizit in webroot/api_routes.php mittels GaiaRoute definiert, und zeigen auf einen von ApiBaseController abgeleiteten Controller.

Beispiel:

Die Route für die SH-spezifische Implementation der freien Termin-Route in api_routes.php:

GaiaRouting::addRoute(
    // Route, relativ zum Backend:
    'api/ktsh/getFreieTermine',
    array(
        'controller' => KtShApiController::class,
        'action' => 'getFreieTermine',
    )
);

Authentifikation

Die Authentifikation erfolgt über einen Usernamen/API-Key, welcher als HTTP Authorization Bearer-Token mitgeschickt wird:

Authorization:Bearer user:key

also z.B.:

Authorization:Bearer apiuser:bbbbbbbb-eeee-8888-9999-aaaaaaaaaaaa

Der Username entspricht dabei einem BISO-Login mit API-Key.

Konfiguration

Damit die API genutzt werden kann, muss ein Login mit einem API-Key und erlaubten Routen konfiguriert werden. Dies passiert mittels biso-cli:

# API-Key für Login erstellen:
php biso-cli api add-key [loginname]

# erlaubte Routen festlegen, hier am Beispiel Kt SH:
php biso-cli api add-route [loginname] api/authKeyTest
php biso-cli api add-route [loginname] api/authKeyTest
php biso-cli api add-route [loginname] api/ktsh/getBesprechungsarten
php biso-cli api add-route [loginname] api/ktsh/getTreffpunkte
php biso-cli api add-route [loginname] api/ktsh/getNationalitaeten
php biso-cli api add-route [loginname] api/ktsh/getAusweiskategorien
php biso-cli api add-route [loginname] api/ktsh/getBerufsberatungen
php biso-cli api add-route [loginname] api/ktsh/getFreieTermine
php biso-cli api add-route [loginname] api/ktsh/sendFormData
php biso-cli api add-route [loginname] api/ktsh/cancelTermin

API-Dokumentation und Build

Wenn neue Routen / neue Endpunkte definiert werden, müssen diese ind er OpenAPI-Doc nachgeführt werden:

doc/api-doc/biso-api.swagger.json.

Die Swagger-/API-Dok unter doc/api-doc wird mittels npm als statische Seite gebuildet und kann dann separat deployt werden:

cd doc/api-doc
npm install
npm run build

Die gebuildete Doku befindet sich dann in doc/api-doc/dist/.