Integraties

Nimbly koppelt met andere systemen in beide richtingen: andere systemen lezen en schrijven je data via de REST API, en je libraries roepen externe diensten aan.

Andere systemen roepen Nimbly aan

Elke resource heeft een REST API. Een aanroeper logt in als Nimbly-gebruiker en krijgt een token:

curl -X POST https://example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "feed@example.com", "password": "…"}'

Het token is 10 minuten geldig en wordt vernieuwd met een GET op hetzelfde adres. Elk request stuurt het mee:

curl "https://example.com/api/v1/projects?filter=published:1&sort=year|desc&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Geef elke integratie een eigen gebruiker en een rol met alleen de rechten die nodig zijn. Een feed die projecten leest, krijgt view-projects; een systeem dat bestellingen aanmaakt, krijgt create-orders. Een gebruiker kan alleen een token aanvragen als API-toegang voor zijn account aan staat. Zet API access aan in het actiepaneel van de gebruiker in de admin, naast het bewerkformulier op /nb-admin/users/<uuid>; daarvoor is een rol nodig die gebruikers mag bewerken. Zet je het uit, dan werkt het token van die gebruiker meteen niet meer. Bewaar de inloggegevens in de eigen geheimenkluis van het aanroepende systeem.

De naslag van de REST API behandelt elke handeling, de queryparameters en de foutcodes, met een OpenAPI-beschrijving.

Eigen endpoints

Heeft een integratie een antwoord nodig dat de resource-API niet geeft, schrijf dan een route met een library. Controleer eerst de toegang, en antwoord dan:

<?php
// ext/lib/order-summary.php

function order_summary_sc($params)
{
    load_library('api');
    if (!api_access('view-orders')) {
        header('Content-Type: application/json', true, 403);
        return json_encode(['message' => 'ACCESS_DENIED']);
    }
    load_library('data');
    $orders = data_query('orders', ['filter' => 'status:open', 'limit' => 100]);
    header('Content-Type: application/json');
    return json_encode(['open' => $orders['total']]);
}

api_access() accepteert de ingelogde gebruiker, een token en uitdrukkelijk toegestane publieke handelingen, dus het endpoint werkt voor de browser en voor andere systemen. Zie Wat een route teruggeeft.

Webhooks

Een betaalprovider of een andere dienst die je site aanroept, is een route zoals elke andere, bijvoorbeeld ext/uri/webhooks/payments/index.tpl met een library die de handtekening controleert, het event vastlegt en de vervolgstap als job in de wachtrij zet. Antwoord snel en doe het werk in de job; zie Werk op de achtergrond.

Nimbly roept andere systemen aan

Een library roept externe diensten aan met de HTTP-hulpfuncties in core/lib/curl.php:

load_library('curl');
load_library('env');
$rates = curl_get('https://api.example.com/rates', ['Authorization: Bearer ' . env('RATES_API_KEY')]);

Bewaar sleutels in .env en lees ze met env(). Aanroepen die traag kunnen zijn, kunnen mislukken of opnieuw moeten, horen in een job, niet in een paginarequest.

Houd het in een module

Een integratie met eigen routes, libraries en data, zoals een betaalprovider met een afrekenpagina en een webhook, is makkelijker te onderhouden en te hergebruiken als module.