Architectuur

Waarom wij kozen voor een
schema-first API-ontwerp

Een diepere kijk in de technische overwegingen achter Formly's architectuur, en waarom JSON Schema de toekomst van formulier-ontwikkeling bepaalt.

Visualisatie van Formly's schema-first architectuur met JSON data
De basis

Het probleem met imperatieve formulier-API's

In de vroege jaren van webontwikkeling deden we precies wat de meeste API's doen: we gaven ontwikkelaars een eindpunt om een formulier te "krijgen" en een ander eindpunt om de resultaten te "sturen".

Het probleem met deze imperatieve benadering is snel duidelijk: elke keer dat je een veld wilt toevoegen of wijzigen, moet je een POST request doen om een nieuwe configuratie op te halen. Als je formulieren complex worden, wordt dit tot een oneindige cyclus van requests en responses. Het beheer van versies wordt een nachtmerrie, en het testen van je applicatie wordt afhankelijk van interne implementatiedetails in plaats van contracten.

Bij Formly besloten we een andere weg in te slaan: we definieerden formulieren niet als acties, maar als statische datastructuren — schema's. Hierdoor is het formulier in essentie een JSON-object dat je kunt versiebeheren, cachen en valideren, zonder dat je daarvoor een server-side rendering engine nodig hebt.

Voordelen

Schema-first: de kracht van standaarden

Door te kiezen voor een schema-first benadering, halen we het beste van twee werelden: de controle van een custom API en de interoperabiliteit van een standaard.

  • Versieerbaarheid

    Je kunt formulieren updaten zonder data te breken. Oudere inzendingen blijven gekoppeld aan het schema van die tijd. Rollbacks zijn eenvoudig via één API-call.

  • Testbaarheid

    Omdat de API verwacht een geldig JSON Schema, kunnen onze tests en jouw frontend-tests dit eenvoudig valideren. Geen moeilijk te simuleren "endpoints" meer.

  • Interoperabiliteit

    Door ons te baseren op JSON Schema (en in de toekomst OpenAPI), kunnen andere tools, linters en validatoren direct met je formulieren werken.

Technisch dieptenkijk

Hoe wij JSON Schema uitbreiden

Formly bouwt bovenop de officiële JSON Schema specificatie. We voegen echter custom properties toe die specifiek zijn voor formulierlogica.

Stel je voor dat je een verplicht veld wilt maken dat alleen zichtbaar is als een ander veld een specifieke waarde heeft. In een imperatief systeem zou je dit in een backend-controller moeten programmeren. Met Formly voegen we de property formly:ui toe aan het schema.

Hier is een voorbeeld van hoe onze extensie eruitziet in de praktijk: 

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "formly:ui": "email-input",
      "formly:validators": {
        "required": true
      }
    },
    "newsletter": {
      "type": "boolean",
      "formly:ui": "toggle",
      "formly:condition": {
        "field": "email",
        "value": "true"
      }
    }
  }
}

Deze aanpak zorgt ervoor dat onze engine de logica direct uit het schema kan afleiden, zonder dat er complexe JavaScript-logica aan de frontend-kant hoeft te draaien.

Afwegingen

Flexibiliteit vs. Complexiteit

Het is niet altijd makkelijk. Een schema-first architectuur vereist dat developers eerst begrijpen hoe JSON Schema werkt voordat ze kunnen beginnen. Het kan op het eerste gezicht wat "vervelend" lijken vergeleken met een simpele drag-and-drop interface.

Onze ervaring is echter dat de inhaalslag voor developers sneller is dan het herkauwen van complexe, onvoorspelbare API-endpoints. De complexiteit is nu expliciet en zichtbaar in je codebase, in plaats van verborgen in server-side logica. Wij hebben geleerd dat voorspelbaarheid winst oplevert boven snelheid in de lange termijn.

Conclusie

OpenAPI publicatie en de toekomst

Na maanden van ontwikkeling en testing zijn we klaar om een stap verder te gaan. We publiceren onze officiële OpenAPI-specificatie. Dit maakt Formly volledig integrerbaar met tools zoals Postman, Swagger UI en OpenAPI-generator frameworks.

Dit markeert het einde van "zwarte doos" API's. Met deze open specificatie kunnen partners en ontwikkelaars hun formulieren automatisch genereren in elke taal en op elk platform. Formly is nu niet alleen een platform om formulieren te bouwen, maar een echte infrastructuur-laag voor data-invoer.

Bekijk OpenAPI op GitHub

Over de auteur

Sarah Vermeer

Senior Backend Developer bij Formly

Sarah heeft 10+ jaar ervaring met enterprise software architectuur. Ze is gepassioneerd door standaarden, open source en het bouwen van tools die developers vrijstellen van repetitieve taken. Op Twitter vind je haar onder @sarahdev.

Reageer op dit artikel