id: https://nde.nl/ontology/hc/class/FileAPI
name: file_api
title: FileAPI Class
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  dcat: http://www.w3.org/ns/dcat#
  dcterms: http://purl.org/dc/terms/
  schema: http://schema.org/
  premis: http://www.loc.gov/premis/rdf/v3/
  xsd: http://www.w3.org/2001/XMLSchema#
imports:
  - linkml:types
  - ../enums/ContentDispositionEnum
  - ../metadata
  - ../slots/has_score
classes:
  FileAPI:
    is_a: DataServiceEndpoint
    class_uri: hc:FileAPI
    description: "File/asset retrieval API for downloading digital content.\n\n**Purpose:**\n\
      \nModels endpoints that provide direct access to digital files\n(images, documents,\
      \ audio, video, 3D models) stored in heritage repositories.\n\n**Distinction\
      \ from Image Servers:**\n\n- **FileAPI**: Downloads original or derivative files\
      \ as-is\n- **IIPImageServer**: Dynamic image delivery with zooming, tiling,\
      \ region extraction\n\nUse FileAPI when you need:\n- Original/master files\n\
      - Fixed-resolution derivatives\n- Non-image files (PDFs, audio, video, office\
      \ documents)\n\n**Example - Nationaal Archief File API:**\n\n```yaml\nfile_api:\n\
      \  endpoint_name: \"Nationaal Archief File API\"\n  base_url: \"https://service.archief.nl/gaf/api/file/v1/\"\
      \n  url_pattern: \"{base_url}{uuid}/{level}/{format}\"\n  version: \"v1\"\n\
      \  supported_levels:\n    - MASTER\n    - HIGH\n    - MEDIUM\n    - LOW\n  \
      \  - THUMBNAIL\n  has_format:  # was: supported_format - migrated 2026-01-16\n\
      \    - image/jpeg\n    - image/png\n    - application/pdf\n  max_file_size_mb:\
      \ 500\n  supports_range_requests: true\n  example_url: \"https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg\"\
      \n```\n\n**Use Cases:**\n\n1. **Download master files**: Archival-quality preservation\
      \ copies\n2. **Generate derivatives**: Request specific size/format\n3. **Batch\
      \ harvesting**: Download all files for a record\n4. **Streaming**: Audio/video\
      \ delivery\n\n**See Also:**\n\n- Content-Disposition header for filename hints\n\
      - HTTP Range requests (RFC 7233) for partial downloads\n"
    comments:
    - Essential for downloading digital content from heritage repositories
    - Master files may have access restrictions
    - Use Range requests for large file downloads
    see_also:
    - https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
    - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
    slots:
    - has_score
    - has_format
    - access_restricted
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: '[''*'']'