Afbeeldingen

Sommige soorten data kun je niet beschrijven met een getal of een tekstveld. Denk aan productfoto’s, profielfoto’s of andere afbeeldingen. In dat soort gevallen gebruik je een speciaal datatype: het afbeeldingsveld (type: image). Hiermee kun je afbeeldingen opslaan in je database, inclusief bijbehorende metadata.

Wat is een afbeeldingsveld?

Een afbeeldingsveld is een speciaal type veld waarmee je een afbeelding kunt koppelen aan een item. Net als andere velden voeg je dit toe onder de fields-key in je collectie. Deze moet altijd op de volgende manier worden opgebouwd:

{
  "name": "imageUrl",
  "type": "image",
  "required": false
}

Afbeeldingen worden in deze database opgeslagen in Base64 formaat. Base64 is een manier om binaire bestanden (zoals afbeeldingen) om te zetten in tekst. Zo kun je ze makkelijk opnemen in JSON. Nadat een afbeelding is opgeslagen en deze zou opvragen, krijg je de volgende informatie terug uit de database:

{
  "imageUrl": {
    "fileName": "logo_under_construction.svg",
    "contentType": "image/svg+xml",
    "length": 26660,
    "base64": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIG..."
  }
}

Validatieregels

Wanneer afbeeldingen worden toegevoegd aan de database worden ze automatisch gecontroleerd op formaat, type en inhoud. Je hoeft hier niets voor in te stellen. Let er wel op dat afbeeldingen voldoen aan de volgende voorwaarden:

Voorbeeld: collectie met afbeeldingsveld

{
  "collections": [
    {
      "name": "products",
      "fields": [
        {
          "name": "id",
          "type": "number",
          "required": true
        },
        {
          "name": "name",
          "type": "string",
          "required": true,
          "min": 2,
          "max": 100
        },
        {
          "name": "price",
          "type": "number",
          "required": false,
          "min": 0,
          "default": 0
        },
        {
          "name": "imageUrl",
          "type": "image",
          "required": false
        },
        {
          "name": "categoryId",
          "type": "reference:categories",
          "required": true
        }
      ]
    }
  ]
}

Afbeelding uploaden

Je kunt afbeeldingen op twee manieren uploaden:

1. Een PATCH-request met multipart/form-data

Normaliter upload je afbeeldingen via een formulier door middel van multipart/form-data. Dit is gebruikelijk voor frontend-implementaties omdat je met meerdere soorten data werkt (denk een aan product waarvan je zowel de naam, prijs en afbeelding in één keer verstuurd). De API verwacht de afbeelding onder de key imageUrl in het FormData-object.

Let op: binnen de NOVI Dynamic API is deze manier alleen mogelijk met een losse PATCH-request waarbij je enkel de afbeelding meestuurt als formdata. Wil je meerdere soorten data wijzigen of toevoegen? Dan zal je de overige data met een losse PATCH-request moeten versturen.

2. Binnen de JSON met base64-encoded inhoud

Bij deze methode verstuur je de afbeelding als onderdeel van een JSON-object. Deze methode is vooral handig wanneer je de database vooraf wil vullen met testdata via je JSON-configuratiebestand. Doe dit altijd volgens deze opbouw:

{
  "imageUrl": {
    "fileName": "product.jpg",
    "contentType": "image/jpeg",
    "length": 12345,
    "base64": "9j4AAQSkZJRgABAQEAYABgAAD..."
  }
}

Hierbij is fileName de naam van het geüploade bestand, contentType het MIME-type, zoals image/jpeg, of image/svg+xml, length de grootte van de afbeelding in bytes en base64 de afbeeldingsdata als base64-gecodeerde string. Er zijn online tooltjes te vinden die een afbeelding voor je converteren naar base64, zoals bijvoorbeeld jam.dev. Zijn je afbeeldingen groter dan 2MB? Verklein ze dan eerst met een compressie-tool, zoals Tiny.