← Examples Gallery

:json: Protocol

The :json: protocol fetches external JSON APIs and maps their data to Alap link items. Unlike :web: which guesses field names, :json: uses explicit configuration: a declared root path, precise field mapping, envelope metadata extraction, and template interpolation.

How It Works

Every :json: source is defined in the config with three key parts:

  1. url — where to fetch, with optional ${1} template vars for dynamic queries
  2. root — dot-path to the data array in the response (omit for bare arrays)
  3. fieldMap — explicit mapping from API fields to AlapLink fields
sources: {
  artic: {
    url: 'https://api.artic.edu/api/v1/artworks/search?q=${1}&limit=12',
    root: 'data',
    envelope: { iiif_url: 'config.iiif_url' },
    fieldMap: {
      label: 'title',
      url: 'https://www.artic.edu/artworks/${id}',
      image: '${_envelope.iiif_url}/${image_id}/full/843,/0/default.jpg',
    },
  },
}

Sources in This Demo

SourceAPIFeatures Demonstrated
countries_europe REST Countries Bare array, nested fields (name.common), thumbnails
music_albums TheAudioDB Positional URL args (${1}), root path, thumbnails, genre tags
artic Art Institute of Chicago Envelope template vars (${_envelope.iiif_url}), IIIF images
wikimedia Wikimedia Commons Nested image info (imageinfo[0].thumburl), HTML stripping on artist/description
openlibrary Open Library Template URLs for covers, author arrays
loc_search Library of Congress (Search) Rich metadata: dates, contributors, formats, locations

Three Renderers, One Config

Each sub-page demonstrates the same :json: sources rendered through a different Alap renderer. The config stays the same — only the UI changes.