# UJS Beispiele: REST API nutzen

Die Beispiele zeigen einen kleinen End-to-End-Test gegen die REST-v1-API:
Token prüfen, JSON-Eintrag speichern, lesen, filtern, aktualisieren, Historie
abrufen und eine einfache Aggregation ausführen.

Die Dateien sind bewusst standalone gehalten. Du kannst sie in andere Projekte
kopieren, ohne den restlichen Projektordner mitzunehmen.

## Dateien

- `example_funktion.phps`: PHP-Funktionen, geeignet für einfache oder alte PHP-Projekte.
- `example_classe.phps`: PHP-Klasse `UjsExampleClient`, geeignet für Projekte mit OOP-Struktur.
- `example.sh`: Shell/cURL-Beispiel, kann ausgeführt oder in Shell-Skripte gesourced werden.
- `example_python.py`: Python-Beispiel ohne externe Pakete.
- `example_python.html`: farbige Ansicht von `example_python.py` mit Copy-Button.

Die PHP-Beispiele `example_funktion.phps` und `example_classe.phps` vermeiden PHP-7/8-Syntax
und sind für PHP 5.5/5.6 bis PHP 8.x geschrieben. Benötigt werden `curl` und
`json`. Zum Einbinden in ein Projekt die jeweilige `.phps`-Datei herunterladen
und im Zielprojekt als `.php` speichern.

## Voraussetzungen

1. Projekt installieren und Datenbank importieren.
2. Adminbereich öffnen: `/admin/`
3. Modul anlegen, zum Beispiel:
   - Slug: `testmodul`
   - Name: `Testmodul`
   - Optional: `optimistic_locking` aktivieren, wenn Versionen getestet werden sollen.
4. Token für dieses Modul erstellen:
   - `read`: aktiv
   - `write`: aktiv
   - `delete`: nur nötig, wenn am Ende automatisch gelöscht werden soll
   - `allowed_types`: leer lassen oder `test_note` erlauben

Die interaktive API-Dokumentation liegt unter `/docs/`. Die OpenAPI-Spezifikation
steht als JSON unter `/openapi.php`.

## Ausführen: PHP-Funktionen

```bash
UJS_BASE_URL=https://dev.jsonstorage.de \
UJS_MODULE=testmodul \
UJS_TOKEN=dein-token \
php example_funktion.php
```

Einbindung:

```php
require_once 'example_funktion.php';

$result = ujs_example_store(
    'https://dev.jsonstorage.de',
    'dein-token',
    'testmodul',
    'test_note',
    'K-1001',
    array('title' => 'Hallo'),
    array('testmodul')
);
```

## Ausführen: PHP-Klasse

```bash
UJS_BASE_URL=https://dev.jsonstorage.de \
UJS_MODULE=testmodul \
UJS_TOKEN=dein-token \
php example_classe.php
```

Einbindung:

```php
require_once 'example_classe.php';

$ujs = new UjsExampleClient('https://dev.jsonstorage.de', 'dein-token', 'testmodul');
$result = $ujs->store('test_note', 'TEST-1001', array('title' => 'Hallo'), array('testmodul'));
```

## Ausführen: Shell

In `example.sh` stehen `UJS_BASE_URL`, `UJS_MODULE`, `UJS_TOKEN` und die
Testdaten direkt oben in der Datei. Das Script kann deshalb ohne weitere
Umgebungsvariablen gestartet werden.

```bash
./examples/example.sh WHOAMI
./examples/example.sh POST
./examples/example.sh POST payload.json
./examples/example.sh POST '{"type":"test_note","customer_no":"TEST-1001","data":{"title":"Hallo"}}'
./examples/example.sh LIST
./examples/example.sh GET 123
```

Einbindung:

```bash
. ./example.sh
ujs_whoami
ujs_post_entry payload.json
```

## Ausführen: Python

Im Browser kann die farbige Ansicht `example_python.html` geöffnet werden. Die
Rohdatei `example_python.py` wird als Text ausgeliefert und kann direkt kopiert
oder heruntergeladen werden.

```bash
UJS_BASE_URL=https://dev.jsonstorage.de \
UJS_MODULE=testmodul \
UJS_TOKEN=dein-token \
python examples/example_python.py
```

Einbindung:

```python
from example_python import UjsClient

ujs = UjsClient('https://dev.jsonstorage.de', 'dein-token', 'testmodul')
result = ujs.store('test_note', 'TEST-1001', {'title': 'Hallo'}, ['testmodul'])
```

Der erzeugte Testeintrag bleibt standardmäßig erhalten, damit er im Adminbereich
angesehen werden kann. Zum automatischen Aufräumen:

```bash
UJS_DELETE_AFTER=1 \
UJS_BASE_URL=https://dev.jsonstorage.de \
UJS_MODULE=testmodul \
UJS_TOKEN=dein-token \
php example_classe.php
```

## Was das Script aufruft

- `GET /api/v1/whoami`
- `POST /api/v1/modules/{slug}/entries`
- `GET /api/v1/modules/{slug}/entries/{id}`
- `GET /api/v1/modules/{slug}/entries`
- `PUT /api/v1/modules/{slug}/entries/{id}`
- `GET /api/v1/modules/{slug}/entries/{id}/history`
- `GET /api/v1/modules/{slug}/aggregate`
- Optional: `DELETE /api/v1/modules/{slug}/entries/{id}`

Alle geschützten Endpunkte senden den Token als Bearer Header:

```http
Authorization: Bearer dein-token
```

Der Request Body beim Anlegen sieht im Kern so aus:

```json
{
  "type": "test_note",
  "customer_no": "TEST-1001",
  "data": {
    "title": "UJS Testeintrag",
    "status": "open",
    "amount": 129.9
  },
  "tags": ["testmodul", "php-client"]
}
```

## Typische Fehler

- `401 auth.missing` oder `auth.invalid`: `UJS_TOKEN` fehlt oder ist falsch.
- `403 auth.forbidden`: Token gehört zu einem anderen Modul oder hat keine Rechte.
- `403 type nicht erlaubt`: Im Token ist `allowed_types` gesetzt, aber `test_note`
  nicht erlaubt.
- `404 Route nicht gefunden`: `UJS_BASE_URL` muss auf die Projektwurzel zeigen,
  nicht auf `/api/v1`.