Web Services API in Joomla

2. JSON:API - het formaat dat Joomla spreekt

2.1 Een gedeelde afspraak

Joomla verzint geen eigen vorm voor de antwoorden. Het volgt JSON:API, een publieke afspraak over hoe een REST-antwoord eruit moet zien. Omdat het formaat een standaard is, begrijpen veel bestaande clientbibliotheken het al, en de structuur is hetzelfde voor artikelen, gebruikers of welke andere resource dan ook.

2.2 De vorm van een enkel item

Een verzoek om een artikel geeft een data-object terug met een type, een id en een attributes-blok dat de eigenlijke velden bevat:

{
  "links": { "self": "https://example.test/api/index.php/v1/content/articles/1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Welcome to my site",
      "alias": "welcome-to-my-site",
      "state": 1,
      "catid": 2,
      "introtext": "..."
    }
  }
}

2.3 De vorm van een lijst

Een lijstverzoek geeft data terug als een array van die objecten, plus een meta-blok met het totale aantal en links om door de resultaten te bladeren. Als je deze vorm een keer kent, kun je elke lijst lezen die de API teruggeeft, ongeacht de resource.

4. Authenticatie - bewijzen wie je bent

4.1 Geen formulier, geen sessie

De website onthoudt je met een sessiecookie nadat je een keer bent ingelogd. De API heeft geen inlogformulier en houdt geen sessie bij. Een programma moet bij elk afzonderlijk verzoek bewijzen wie het is. Joomla ondersteunt twee methodes, beide afgehandeld door de plugingroep api-authentication.

4.2 Token-authenticatie (aanbevolen)

Elke gebruiker krijgt een persoonlijk token, een lange geheime tekenreeks, en stuurt dat als header mee bij elke aanroep. Er verlaat nooit een wachtwoord de server, en een token kan op zichzelf worden ingetrokken zonder het wachtwoord van de gebruiker te wijzigen.

curl -H "X-Joomla-Token: <your-token>" \
     https://example.test/api/index.php/v1/content/articles

# Joomla accepteert ook de standaard Authorization-header (Bearer is hoofdlettergevoelig):
curl -H "Authorization: Bearer <your-token>" \
     https://example.test/api/index.php/v1/content/articles

Om tokens te laten werken, schakel je twee plugins in en genereer je een token:

1. Schakel de plugin User - Joomla API Token in (deze voegt het tokenveld toe aan gebruikersprofielen).
2. Schakel de plugin API Authentication - Token in (deze leest de header bij elk verzoek).
3. Open het profiel van de gebruiker, zoek het tabblad Joomla API Token en genereer een token. Kopieer het meteen: Joomla bewaart alleen een seed, dus het kan het token niet nog eens aan je tonen.

Standaard mogen alleen Super Users een token gebruiken. Verbreed dit via de parameter allowedUserGroups van de plugin User - Joomla API Token, en houd die lijst zo smal als de taak toelaat.

4.3 Basic-authenticatie

De plugin API Authentication - Web Services Basic laat een client bij elk verzoek een gebruikersnaam en wachtwoord meesturen, via standaard HTTP Basic-auth:

curl -u myusername:mypassword \
     https://example.test/api/index.php/v1/content/articles

Het is eenvoudig, maar het stuurt het echte accountwachtwoord bij elke aanroep mee. Gebruik het alleen over HTTPS, en geef voor alles wat langdurig is de voorkeur aan tokens, want een gelekt wachtwoord is veel schadelijker dan een gelekt token dat je kunt intrekken.

4.4 Publieke routes

Een paar routes kunnen als publiek worden gemarkeerd, wat betekent dat ze antwoorden zonder enige inloggegevens. De meeste schrijfroutes zijn nooit publiek. Leesroutes zijn alleen publiek wanneer de Web Services-plugin van de component daarvoor kiest. Behandel publieke toegang als de uitzondering, niet de regel, en stel nooit schrijfmethodes op die manier beschikbaar.

6. Lijsten bevragen

6.1 Door resultaten bladeren

Een lijst geeft niet alle rijen in een keer terug. Joomla blader door de resultaten met de offset-notatie van JSON:API. Je bepaalt het venster met twee query-parameters:

curl -H "X-Joomla-Token: <your-token>" \
  "https://example.test/api/index.php/v1/content/articles?page[limit]=20&page[offset]=0"

Het meta-blok in het antwoord vertelt je het totale aantal, zodat je weet hoeveel pagina's er zijn.

6.2 Sorteren

Sorteer een lijst met list[ordering] voor de kolom en list[direction] voor de richting (asc of desc). Joomla controleert de kolom tegen de toegestane filters van het model, dus je kunt niet op een willekeurig veld sorteren:

"...?list[ordering]=created&list[direction]=desc"

6.3 Filteren

Versmal een lijst met filter[...]-parameters. De beschikbare filters hangen af van de component, en ze komen overeen met dezelfde filters die de backend-lijst gebruikt. Voor artikelen kun je bijvoorbeeld filteren op categorie of op publicatiestatus:

"...?filter[catid]=2&filter[state]=1"

6.4 Velden kiezen

Om een antwoord klein te houden, vraag je alleen om de velden die je nodig hebt met de JSON:API-parameter fields, met vermelding van het resource-type:

"...?fields[articles]=title,catid,state"

Vergeet niet de vierkante haken URL-te-coderen en de hele URL tussen aanhalingstekens te zetten in je shell, anders worden de haken en ampersands verkeerd gelezen.

8. Onder de motorkap (ontwikkelaarsblik)

8.1 De reis van een verzoek

Een API-verzoek legt een duidelijk pad af van URL naar JSON:

/api/index.php   →  API-applicatie start op
                 →  ApiRouter koppelt de URL aan een route
                 →  een api-authentication-plugin controleert het token
                 →  de ApiController van de component draait (list/item/add/...)
                 →  een ListModel/AdminModel haalt of bewaart de data
                 →  een JsonapiView + serializer bouwen het JSON:API-antwoord

8.2 Routes komen uit plugins

De API heeft geen vaste routetabel. Elke Web Services-plugin luistert naar de gebeurtenis onBeforeApiRoute en registreert zijn eigen routes wanneer de router wordt opgebouwd. De com_content-plugin doet dit bijvoorbeeld:

public function onBeforeApiRoute(BeforeApiRouteEvent $event): void
{
    $router = $event->getRouter();

    $router->createCRUDRoutes(
        'v1/content/articles',
        'articles',
        ['component' => 'com_content']
    );
}

De helper createCRUDRoutes() is de reden dat de meeste resources dezelfde vorm met vijf werkwoorden delen. Een aanroep wordt uitgebreid tot alle vijf REST-routes:

GET    v1/content/articles        → articles.displayList
GET    v1/content/articles/:id    → articles.displayItem
POST   v1/content/articles        → articles.add
PATCH  v1/content/articles/:id    → articles.edit
DELETE v1/content/articles/:id    → articles.delete

Het vierde argument, $publicGets, bepaalt of de twee GET-routes antwoorden zonder authenticatie. De standaardwaarde is false.

8.3 De controller en view

Elke component heeft een dunne API-laag onder api/components/com_xxx/. Een controller breidt ApiController uit en hergebruikt dezelfde modellen als de backend. Hij leest de parameters voor paginering, sortering en filtering uit het verzoek, draait het model en geeft het resultaat door aan een JsonapiView. Een serializer zet vervolgens het Joomla-object om in de JSON:API-vorm met type / id / attributes.

api/components/com_content/src/
├─ Controller/ArticlesController.php   (extends ApiController)
├─ View/Articles/JsonapiView.php       (renders JSON:API)
└─ Serializer/ContentSerializer.php    (maps fields to attributes)

Omdat de API de bestaande modellen hergebruikt, draaien dezelfde validatie, toegangscontroles en gebeurtenissen die in de backend lopen ook voor een API-aanroep. De API is een nieuw gezicht op dezelfde motor, niet een parallelle motor.

8.4 Betrokken tabellen

8.5 Je eigen endpoint toevoegen

Om een eigen component over de API beschikbaar te stellen, schrijf je een kleine webservices-plugin die routes registreert op onBeforeApiRoute, plus een API-controller, view en serializer onder de map api/ van je component. Je past nooit de core aan en raakt nooit de bestaande routes aan. Dit is hetzelfde mechanisme dat elke kerncomponent gebruikt, wat betekent dat een externe extensie als volwaardig burger aan de API kan meedoen.

10. Verder gaan: headless, AI en schaal

Zodra de API de manier is waarop je content Joomla verlaat, volgt er een grotere vraag: wat verbruikt het? Hier houdt Joomla op alleen een website te zijn en wordt het een contentplatform. Dezelfde JSON die je al aanroept, kan een ontkoppelde frontend, een AI-assistent of een hele vloot aan kanalen tegelijk voeden.

• Headless Joomla. Laat de eigen weergave van Joomla vallen en laat een aparte frontend (React, Vue, Next.js, een mobiele app) de pagina's tekenen vanuit de API. Joomla wordt een pure contentopslag.
• AI en RAG. Omdat elk artikel schone JSON is, vormt Joomla een natuurlijke bron van waarheid voor chatbots en Retrieval-Augmented Generation-pijplijnen die antwoorden uit je eigen content halen.
• Prestaties en schaal. Een drukke API-opzet leunt op paginering, caching (Redis, Varnish, CDN), rate limiting en token-rotatie om snel en veilig te blijven.

Deze onderwerpen vormen op zichzelf een architectuuronderwerp, dus ze hebben hun eigen begeleidende artikel. Voor het volledige plaatje - ontkoppelde frontends, een Next.js-voorbeeld, AI-chatbots, RAG en vectordatabases, MCP, AI-agents, caching en SEO voor een ontkoppelde site - zie het aparte Focus On-artikel over Joomla als headless website. Dit artikel blijft gericht op de API zelf: hoe hij werkt, hoe je hem aanroept en hoe je hem beveiligt.

12. Veelgemaakte fouten en valkuilen

12.1 De API staat uit

Symptoom: elke aanroep geeft een foutmelding, zelfs een simpele leesactie.

Oplossing: schakel de Web Services API in via Systeem → Algemene configuratie. Hij staat standaard uit op een nieuwe site.

12.2 De componentplugin is uitgeschakeld

Symptoom: een resource geeft 404 terwijl een andere prima werkt.

Oplossing: schakel de bijbehorende webservices-plugin in. Zonder die plugin registreert die component geen routes.

12.3 Het token wordt geweigerd (401)

Symptoom: een token dat er correct uitziet wordt geweigerd als niet-geautoriseerd.

Oplossing: controleer drie dingen. De plugin API Authentication - Token moet ingeschakeld zijn, de gebruiker moet behoren tot een groep die in allowedUserGroups staat, en het account mag niet geblokkeerd zijn of wachten op activatie. Onthoud dat het sleutelwoord Bearer hoofdlettergevoelig is.

12.4 De shell vreet de URL op

Symptoom: paginering of filtering wordt genegeerd, of de shell geeft een foutmelding.

Oplossing: zet de hele URL tussen aanhalingstekens en escape de ampersand. Vierkante haken en & hebben een speciale betekenis in de meeste shells, dus "...?page[limit]=20&page[offset]=0" heeft de aanhalingstekens nodig.

12.5 De Content-Type vergeten

Symptoom: een POST of PATCH maakt niets aan, of de body wordt genegeerd.

Oplossing: stuur Content-Type: application/json mee bij elke schrijfactie, en zorg dat de body geldige JSON is.

12.6 Verwachten dat de API rechten omzeilt

Symptoom: een aanroep wordt geweigerd hoewel het token geldig is.

Oplossing: de gebruiker achter het token heeft hetzelfde recht nodig dat hij in de backend zou nodig hebben. Geef de juiste groep toegang; zoek niet naar een API-only override, want die bestaat niet.

14. In het kort

BASE URL     https://example.test/api/index.php/v1/...

VERBS        GET     read (list or single item)
             POST    create
             PATCH   update (only the fields you send)
             DELETE  remove

AUTH         X-Joomla-Token: <token>        (recommended)
             Authorization: Bearer <token>   (Bearer is case-sensitive)
             curl -u user:pass               (Basic, HTTPS only)

ACL          core.create  core.edit  core.edit.state  core.delete
             401 = not authenticated   403 = not authorised

LIST QUERY   page[limit]=20  page[offset]=0
             list[ordering]=created  list[direction]=desc
             filter[catid]=2  filter[state]=1
             fields[articles]=title,catid,state

ENDPOINTS    v1/content/articles      v1/content/categories
             v1/users                 v1/users/groups
             v1/menus/site/items      v1/contacts
             v1/banners               v1/tags
             v1/media/files           v1/extensions

ENABLE       Global Config        turn the API on
             webservices plugin   per component (routes)
             api-auth + user      Token plugins (login)

SCALE        page large lists, request only needed fields
             caching, CDN, rate limiting: see the headless article

DIAGNOSE     SELECT name, folder, enabled FROM #__extensions
             WHERE folder IN ('webservices','api-authentication');