OpenAPI-server voor Delphi

In één oogopslag

TsgcOpenAPIServer

Eén Delphi-component dat een OpenAPI-specificatie omtovert tot een draaiende, gevalideerde, zelf-documenterende HTTP/2-server.

Componentklasse

TsgcOpenAPIServer

Transport

HTTP/1.1, HTTP/2, WebSocket-upgrade, TLS via OpenSSL of SChannel

Spec-formaten

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (automatisch geconverteerd)

Platforms

Windows, Linux, macOS — Delphi 7 tot 13, C++Builder, FPC

Editie

Standard / Professional / Enterprise — alle bevatten de server

Gebouwd op

sgcWebSockets HTTP-server (zelfde pipeline voor TLS, HTTP/2, auth en logging)

Twee manieren om te bouwen

Spec-first of Code-first — jij kiest

Hetzelfde component draait in beide modi. Begin met een YAML/JSON-contract, of beschrijf de API in Delphi en laat het component de spec voor je publiceren.

1. Spec-first

Laad openapi.yaml, koppel handlers aan operation IDs en begin met serveren. Routes, parameter-binding, content negotiation en validatie komen direct uit het contract — jij schrijft alleen de business logic.

Het beste voor: teams met een gedeeld design-contract, API-led integratie of polyglot back-ends waar de spec de bron van waarheid is.

2. Code-first

Registreer handlers in Pascal met annotaties (path, verb, request-schema, response-schema, security). Het component bouwt het OpenAPI-document tijdens runtime en stelt het beschikbaar op /openapi.json.

Het beste voor: snel prototypen, interne services of het overzetten van een bestaande TIdHTTPServer / DataSnap REST-surface naar een zelf-documenterende API.

Snelstart

Een werkende server in 20 regels

Sleep het component op een form, wijs het naar een OpenAPI-document, koppel één operatie, druk op Run. Dat is de hele setup.

Delphi

uses
  sgcOpenAPI_Server, sgcOpenAPI_Types, sgcHTTP_Server;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcOpenAPIServer.Create(nil);
  FServer.HTTPServer := sgcHTTPServer1;        // reuse the sgcWebSockets HTTP/2 server
  FServer.Spec.LoadFromFile('petstore.yaml');  // any OpenAPI 3.x doc
  FServer.PublishSpecPath := '/openapi.json';
  FServer.SwaggerUIPath   := '/docs';
  FServer.RedocPath       := '/redoc';

  // Bind one operation defined in the spec (operationId = "getPetById")
  FServer.OnOperation_getPetById :=
    procedure(const Ctx: TsgcOpenAPIContext)
    var
      oPet: TJSONObject;
    begin
      oPet := TJSONObject.Create;
      oPet.AddPair('id',     Ctx.PathParams['petId']);
      oPet.AddPair('name',   'Rex');
      oPet.AddPair('status', 'available');
      Ctx.RespondJSON(200, oPet);
    end;

  sgcHTTPServer1.Port   := 8080;
  sgcHTTPServer1.Active := True;
end;

Wat je out of the box krijgt: GET /pets/{petId} serveert de bovenstaande handler, GET /openapi.json retourneert de live spec, GET /docs opent Swagger UI, GET /redoc opent Redoc — met HTTP/2 en TLS al actief als sgcHTTPServer1 dat heeft geconfigureerd.

Routing

Parameters die in het OpenAPI-document gedeclareerd zijn, worden geparset, type-gecontroleerd en blootgesteld via één getypeerde context. Verkeerde types geven 400 Bad Request voordat je handler überhaupt draait.

Delphi

// spec snippet
//   /pets:
//     get:
//       operationId: listPets
//       parameters:
//         - name: limit       in: query    schema: { type: integer, maximum: 100 }
//         - name: status      in: query    schema: { type: string, enum: [available, pending, sold] }
//         - name: X-Tenant-Id in: header   required: true

FServer.OnOperation_listPets :=
  procedure(const Ctx: TsgcOpenAPIContext)
  var
    vLimit:  Integer;
    vStatus: string;
    vTenant: string;
  begin
    vLimit  := Ctx.QueryParamInt('limit', 20);     // default 20
    vStatus := Ctx.QueryParam   ('status', 'available');
    vTenant := Ctx.HeaderParam  ('X-Tenant-Id');   // required → validated

    Ctx.RespondJSON(200, PetRepo.List(vTenant, vStatus, vLimit));
  end;

Validatie

Schema-validatie in beide richtingen

Elke binnenkomende body wordt gevalideerd tegen het requestBody-schema van de operatie. Elke response wordt gevalideerd tegen de gedeclareerde statuscode. Afwijkingen geven RFC 7807 problem-details met diagnostiek op veldniveau.

Request-validatie

Verplichte velden, type-coercie, enum-lidmaatschap, format-validators (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — alles wordt afgedwongen voordat je handler draait.

Response-validatie

Optioneel in productie, strikt tijdens ontwikkeling. Helpt je de dag te vangen waarop je handler een extra veld retourneert dat niet in het contract staat, voordat een downstream-consument breekt.

Eigen validators

Haak in op OnBeforeValidate om domeinregels toe te voegen (valuta-code wordt ondersteund, SKU bestaat, tenant is actief). Levert dezelfde RFC 7807-envelope als de ingebouwde validators voor uniforme foutmelding-UX.

JSON — voorbeeld 400-response

{
  "type":   "https://example.com/probs/validation",
  "title":  "Request body failed schema validation",
  "status": 400,
  "errors": [
    { "path": "/email",    "message": "not a valid email address" },
    { "path": "/age",      "message": "value 213 exceeds maximum 120" },
    { "path": "/status",   "message": "value 'archived' not in enum [active,pending]" }
  ]
}

Beveiliging

Auth-schemes rechtstreeks uit de spec aangesloten

Elk in het document gedeclareerd securityScheme wordt automatisch afgedwongen. Jij schrijft alleen de credential-lookup — het component doet het parsing, de challenge-headers en de 401/403-responses.

API Key

Header, query of cookie. Meerdere keys per operatie. Vergelijking in constante tijd.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 met realm-ondersteuning. Credentials worden nooit gelogd.

JWT (RS256 / ES256 / HS256)

JWKS automatisch ophalen en cachen. Controles op issuer, audience, vervaldatum en custom claims.

OAuth2

Authorization Code, Client Credentials, Password en Implicit flows. PKCE ondersteund.

OpenID Connect

Discovery-document geladen vanaf /.well-known/openid-configuration. ID-token gevalideerd tegen JWKS.

mTLS

Client-certificaat per operatie afdwingbaar. Common Name en SAN beschikbaar in de context.

Delphi — JWT-validatie-hook

FServer.Security.JWT.JWKSUri := 'https://auth.example.com/.well-known/jwks.json';
FServer.Security.JWT.Audience := 'api.example.com';
FServer.Security.JWT.Issuer   := 'https://auth.example.com/';

FServer.OnAuthorize :=
  procedure(const Ctx: TsgcOpenAPIContext; var Allow: Boolean)
  begin
    // Token already verified. Apply business rule on a custom claim.
    Allow := Ctx.JWT.Claims['tenant'] = Ctx.PathParams['tenant'];
  end;

Zelf-documenterend

Swagger UI & Redoc ingebouwd

Geen externe afhankelijkheden, geen Node.js, geen swagger-codegen in de deploy-pipeline. Beide UI's zitten verpakt in het component en worden tijdens runtime rechtstreeks vanuit de spec geserveerd.

/openapi.json & /openapi.yaml

Het live document — altijd in sync met wat de server daadwerkelijk serveert. Wijs elke client-generator (sgcOpenAPI, openapi-generator, oapi-codegen) op deze URL.

/docs — Swagger UI

De vertrouwde interactieve Swagger UI — probeer operaties, blader schemas, bekijk voorbeelden. Configureerbare thema's, deepLinking en OAuth2-redirect.

/redoc — Redoc

De strakke drie-pane-layout van Redoc voor API-documentatie met een statisch gevoel. Zelfde bron, andere presentatie.

Wire-formaten

Content negotiation zoals het hoort

application/json

UTF-8, strikt RFC 8259. Getallen, booleans, nulls, geneste objecten en arrays.

application/yaml

YAML 1.2 met schema-bewuste parsing. Handig voor handgeschreven request-bodies.

application/x-www-form-urlencoded

Klassieke form-posts — gebonden aan het request-schema net als elke andere body.

multipart/form-data

Bestandsuploads met groottelimieten, MIME-type allow lists en schema-binding per part.

text/event-stream (SSE)

Langlopende gestreamde responses — hergebruikt de SSE-writer van sgcWebSockets.

application/octet-stream

Raw binaire download/upload met byte-range request-ondersteuning.

Integratie

Eén HTTP-server, vele surfaces

TsgcOpenAPIServer plugt in op dezelfde sgcWebSockets HTTP/2-server die je WebSocket-endpoints, AI/LLM-streams en statische bestanden host. Eén poort, één TLS-certificaat, één logstroom.

HTTP/2-multiplexing

Honderden REST-operaties en een langlevende WebSocket-abonnement delen dezelfde TLS-verbinding. Browser-clients krijgen een handshake in één rondje, jij hebt minder sockets in leven te houden.

WebSocket-promotie

Declareer x-sgc-upgrade: websocket op een path en het component voert de RFC 6455-upgrade voor je uit — dezelfde operatie doet zowel REST als bidirectionele streaming.

Routes voor statische assets

Zet de SPA-build onder /app op hetzelfde component — nette URL's, gzip, brotli, ETag en HTTP/2 server-push gratis.

Waar het schittert

Typische deployments

Publieke REST API's

Versioned, contract-getest, met auto-gegenereerde SDK's die je klanten kunnen downloaden vanaf /openapi.json.

Interne microservices

Service-tot-service contracten die refactors overleven — de spec is de integratietest.

Industriële / IoT-gateways

Edge-devices die een gedocumenteerd REST-control plane plus een MQTT- of WebSocket-telemetrie-surface bieden vanuit dezelfde Delphi-binary.

Webhook-ontvangers

De webhook-payload van elke provider wordt een getypeerde Pascal-record — Stripe, GitHub, Twilio, Slack — met validatie en idempotentie ingebouwd.

Legacy-modernisering

Verpak een oude DataSnap- of RemObjects-back-end achter een schone OpenAPI-surface zonder de business logic te herschrijven.

BFF (Backend-for-Frontend)

Aggregeer twee of drie upstream-API's achter één spec die past bij de consument — je SPA of mobiele app praat met één getypeerde endpoint.

Beter samen