API Endpoints Handleiding

REST API's bouwen voor externe integraties

Wat is een API Endpoint?

Een API endpoint is een REST-interface waarmee externe systemen data kunnen ophalen uit of schrijven naar je database. SQLio ondersteunt de vier standaard HTTP-methoden: GET (ophalen), POST (aanmaken), PATCH (bijwerken) en DELETE (verwijderen).

Elk endpoint krijgt automatisch een URL en wordt gedocumenteerd in de Swagger/OpenAPI omgeving. Externe systemen kunnen de API aanroepen met een API key en Basic authenticatie.

API Endpoint aanmaken

Stap 1: Navigeer naar API Beheer

Klik in het menu op API configuratie. Je ziet een overzicht van alle bestaande endpoints, gegroepeerd per tag.

Stap 2: Klik op "Nieuw"

Bovenaan verschijnt een formulier. Een nieuw endpoint staat standaard op Inactief; zet de status aan als het aangeroepen mag worden.

Stap 3: Basisinstellingen invullen

De URL wordt automatisch opgebouwd uit de URL-prefix van de omgeving, de subprefix van de databron (connectie-alias) en de naam: /api/[omgeving]/[databron]/{ApiNaam}.

Dezelfde naam mag bestaan met verschillende HTTP-methodes (bijv. GET en POST op orders).

Stap 4: HTTP Methode en brontype kiezen

Stap 5: Opslaan en databronnen kiezen

Bij opslaan vraagt SQLio om een versie en een notitie. Daarna verschijnt de kaart Bereikbaar via databronnen: vink aan via welke connectie-aliassen het endpoint bereikbaar is. Je ziet direct de URL per databron. Alleen databronnen waarop de dataset mag draaien zijn te kiezen.

GET Endpoint

Een GET endpoint haalt data op uit de database via een gekoppelde dataset.

Configuratie

1. Selecteer HTTP Method: GET
2. Kies een Dataset uit de dropdown
3. Optioneel: schakel Paginering in (zie verderop)

Hoe het werkt

De dataset wordt uitgevoerd met eventuele query parameters als filters:

GET /api/GetCustomers?status=actief&city=Amsterdam

De parameters status en city worden doorgegeven aan de dataset WHERE-condities. Het resultaat is de JSON-output van de dataset.

Voorbeeld response

[
  {
    "klantnummer": "K001",
    "naam": "ACME Corp",
    "stad": "Amsterdam",
    "status": "actief"
  },
  {
    "klantnummer": "K002",
    "naam": "Widgets BV",
    "stad": "Amsterdam",
    "status": "actief"
  }
]

POST Endpoint

Een POST endpoint maakt nieuwe records aan in de database. De data wordt meegegeven als JSON body.

Configuratie met Table

1. Selecteer HTTP Method: POST
2. Selecteer Execution Type: Table
3. Kies de tabel waarin records worden aangemaakt
4. Optioneel: selecteer een Response Dataset die de response levert na de insert

SQLio genereert automatisch de INSERT-query. Identity-kolommen en auto-gegenereerde velden (zoals CreatedAt) worden automatisch uitgesloten van de body.

Configuratie met Stored Procedure

1. Selecteer HTTP Method: POST
2. Selecteer Execution Type: Stored Procedure
3. Vul het Execution Statement in:

EXEC dbo.sp_InsertOrder
    @CustomerNo = :CustomerNo,
    @Description = :Description,
    @UserCode = N'SYSTEM'

Body Parameters

Bij een POST worden de parameters als body parameters behandeld. De Swagger documentatie toont ze als JSON request body.

Per parameter kun je instellen:

Parameter Mapping

Bij een Stored Procedure toont SQLio automatisch een Parameter Mapping sectie:

• Gevonden SP parameters: de parameters die in het Execution Statement zijn gedetecteerd
• Matched parameters: parameters die overeenkomen met je body parameters (groen vinkje)
• Niet-gemapte parameters: parameters die niet gekoppeld zijn (waarschuwing)

Voorbeeld aanroep

POST /api/CreateOrder
Content-Type: application/json

{
  "CustomerNo": "K001",
  "Description": "Nieuwe bestelling Q1"
}

Response Dataset

Als je een Response Dataset hebt gekoppeld, worden de resultaten van de INSERT/SP gebruikt als parameters voor de dataset. Zo kun je na het aanmaken direct het volledige record terugsturen:

{
  "orderId": 100,
  "customerNo": "K001",
  "description": "Nieuwe bestelling Q1",
  "orderDate": "2024-01-15",
  "status": "Nieuw"
}

PATCH Endpoint

Een PATCH endpoint werkt een bestaand record bij. De identifier gaat via de URL en de te wijzigen data via de JSON body.

Configuratie met Table

1. Selecteer HTTP Method: PATCH
2. Selecteer Execution Type: Table
3. Kies de tabel
4. URL parameters worden automatisch gegenereerd op basis van de primary keys van de tabel

Configuratie met Stored Procedure

1. Selecteer HTTP Method: PATCH
2. Selecteer Execution Type: Stored Procedure
3. Vul het Execution Statement in:

EXEC dbo.sp_UpdateCustomer
    @CustomerId = :customerId,
    @Name = :name,
    @Email = :email

4. Voeg een URL Parameter toe voor de identifier (bijv. customerId)

URL Parameters

Bij PATCH (en DELETE) worden URL parameters in het pad opgenomen:

PATCH /api/UpdateCustomer/123

De parameter 123 wordt gekoppeld aan customerId. In de Swagger documentatie verschijnen deze als path parameters.

De body bevat alleen de te wijzigen velden:

{
  "name": "Nieuwe naam",
  "email": "nieuw@email.nl"
}

Voorbeeld SQL

SQLio genereert automatisch:

UPDATE [dbo].[Customers]
SET Name = @body_Name, Email = @body_Email
WHERE CustomerId = @url_CustomerId

DELETE Endpoint

Een DELETE endpoint verwijdert een record op basis van de identifier in de URL.

Configuratie

1. Selecteer HTTP Method: DELETE
2. Selecteer Execution Type: Table of Stored Procedure
3. Voeg een URL Parameter toe voor de identifier

Voorbeeld aanroep

DELETE /api/DeleteCustomer/123

Response

Paginering

Voor GET endpoints met grote datasets kun je cursor-based paginering inschakelen.

Instellen

1. Zet de Paginering toggle aan
2. Stel de Page Size in (1 tot 10.000 records per pagina)
3. Optioneel: vink Totaal tonen aan om het totale aantal records mee te geven
4. Selecteer de Cursor Kolommen — meestal de primary key

Hoe het werkt

Eerste pagina (zonder cursor):

GET /api/test/verkooporders

Response:

{
  "data": [
    { "customerId": 1, "name": "ACME Corp" },
    { "customerId": 2, "name": "Widgets BV" },
    ...
  ],
  "pageSize": 50,
  "hasMore": true,
  "after": "50",
  "totalCount": 1250
}

Volgende pagina (met cursor):

GET /api/test/verkooporders?after=350202

De paginagrootte komt uit de configuratie van het endpoint; de aanroeper geeft alleen after mee. totalCount staat alleen in het antwoord als Totaal tonen aan staat. Child layers (bijvoorbeeld regels en klant) worden per record meegeleverd, net als zonder paginering.

Het veld after bevat de cursor-waarde van het laatste record. Bij meerdere cursor-kolommen worden de waarden gescheiden met een pipe: 123|2024-01-15.

Authenticatie

Elke API-aanroep vereist twee vormen van authenticatie:

1. Basic Authentication

Authorization: Basic base64(gebruikersnaam:wachtwoord)

De gebruiker wordt aangemaakt in API gebruikersbeheer: gebruikersnaam, e-mail, volledige naam, bedrijf en wachtwoord (zelf invullen of laten genereren).

2. API Key

X-API-Key: ak_64hexadecimaletekens

De API key wordt gegenereerd per gebruiker per omgeving, via de knop Keys bij de gebruiker. Kopieer de sleutel direct: SQLio toont hem maar één keer.

API key beheer

Per gebruiker kun je:

Endpoint permissies

Niet elke gebruiker heeft toegang tot elk endpoint. Via de knop Rechten bij de gebruiker vink je per omgeving aan welke endpoints hij mag aanroepen. De endpoints zijn gegroepeerd per tag; met het vinkje in de kop selecteer je de hele groep.

Swagger documentatie

SQLio genereert automatisch Swagger/OpenAPI documentatie voor alle actieve, externe endpoints.

Toegang

Ga naar /api-docs (of klik op Swagger Documentatie in API configuratie). Je logt eerst in met een API-gebruiker op de loginpagina /api-login.

Er is een aparte definitie per omgeving en databron, bijvoorbeeld Test APIs en Test (be) APIs. Kies de definitie rechtsboven.

Wat je ziet

• Alle endpoints gegroepeerd op Tag
• Per endpoint: HTTP methode, URL, beschrijving
• Request schema: welke parameters/body velden verwacht worden
• Response schema: de JSON structuur van het antwoord
• Try it out: direct testen vanuit de browser
• Authorize: vul gebruikersnaam, wachtwoord en API-sleutel in

Swagger instellingen

Met de knop Swagger Instellingen in API configuratie pas je de Swagger-pagina aan:

Statistieken

In het API overzicht worden per endpoint statistieken bijgehouden:

HTTP Status Codes

Succes

Client fouten

Server fouten

Foutcodes gebruiken in Stored Procedures

Je kunt vanuit een stored procedure specifieke HTTP status codes retourneren via RAISERROR:

-- 400 Bad Request (state 1, 2 of 10)
RAISERROR('Klantnummer is verplicht', 16, 1)

-- 404 Not Found (state 20)
RAISERROR('Klant niet gevonden', 16, 20)

De State parameter bepaalt welke HTTP status code wordt teruggestuurd.

Compleet voorbeeld: CRUD API voor klanten

GET — Alle klanten ophalen

• API Naam: GetCustomers
• HTTP Method: GET
• Dataset: Klanten dataset
• Paginering: Aan, 50 per pagina

GET /api/GetCustomers?pageSize=50

GET — Eén klant ophalen

• API Naam: GetCustomer
• HTTP Method: GET
• Dataset: Klant detail dataset (met WHERE op :customerId)

GET /api/GetCustomer?customerId=K001

POST — Nieuwe klant aanmaken

• API Naam: CreateCustomer
• HTTP Method: POST
• Execution Type: Table
• Tabel: dbo.Customers
• Response Dataset: Klant detail dataset
• HTTP Status: 201 Created

POST /api/CreateCustomer
Content-Type: application/json

{
  "Name": "Nieuw Bedrijf BV",
  "City": "Rotterdam",
  "Email": "info@nieuwbedrijf.nl"
}

Response:

{
  "customerId": "K042",
  "name": "Nieuw Bedrijf BV",
  "city": "Rotterdam",
  "email": "info@nieuwbedrijf.nl",
  "createdAt": "2024-01-15T10:30:00"
}

PATCH — Klant bijwerken

• API Naam: UpdateCustomer
• HTTP Method: PATCH
• Execution Type: Table
• Tabel: dbo.Customers
• URL Parameter: customerId (String, Required)

PATCH /api/UpdateCustomer/K042
Content-Type: application/json

{
  "City": "Amsterdam",
  "Email": "nieuw@nieuwbedrijf.nl"
}

DELETE — Klant verwijderen

• API Naam: DeleteCustomer
• HTTP Method: DELETE
• Execution Type: Table
• Tabel: dbo.Customers
• URL Parameter: customerId (String, Required)

DELETE /api/DeleteCustomer/K042

Veelvoorkomende problemen