REST-API Basics

Alle aYOUne-APIs folgen einem konsistenten Muster: Bearer-Auth, JSON-Envelope, Cursor- oder Offset-Pagination. Wer ein Modul kennt, kennt sie alle.

Authentication-Header

GET /consumers HTTP/1.1
Host: crm-api.ayoune.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
Accept: application/json

Token-Quellen (in dieser Reihenfolge ausprobiert):

1. Authorization: Bearer <jwt> — Standard
2. ?token=<jwt> Query-Param — nur für Datei-Downloads sinnvoll
3. WebSocket-Handshake — Sec-WebSocket-Protocol: bearer.<jwt>

JSON-Envelope

Jede Antwort ist mit defaultAPIAnswer einheitlich strukturiert:

{
  "payload": {
    "data": [/* Liste oder einzelnes Objekt */],
    "entries": 17,
    "audit": [],
    "fields": []
  },
  "meta": {
    "pageInfo": { "totalEntries": 412, "page": 1, "limit": 25 },
    "version": "2026.50.0",
    "debugId": "..."
  }
}

payload.data ist die einzige verlässliche Stelle für die eigentliche Nutzlast. Das Feld meta.pageInfo.totalEntries ersetzt einen separaten /count-Call (nutze ihn für Pagination-UIs).

Pagination

Beispiel:

curl "https://crm-api.ayoune.app/consumers?limit=50&page=2&sort=createdAt:-1&fields=email,first_name,last_name" \
  -H "Authorization: Bearer $TOKEN"

Filtering

Die Plattform unterstützt MongoDB-ähnliche Filter direkt in der URL:

curl "https://crm-api.ayoune.app/consumers?email=*@example.com&_status=active"

Komplexere Queries laufen via POST /aggregate:

curl -X POST https://aggregation.ayoune.app/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Consumers",
    "pipeline": [
      { "$match": { "_status": "active" } },
      { "$group": { "_id": "$country", "count": { "$sum": 1 } } }
    ]
  }'

HTTP-Methoden

Custom-Actions laufen unter /{plural}/:id/actions/<action-name> — siehe API-Reference.

Nächste Schritte

• CORS & Auth — Browser-Aufrufe
• Error Codes — was tun bei 4xx/5xx