# File API Class
# Represents file/asset retrieval endpoints for downloading digital content
#
# File APIs provide access to the actual digital files (images, documents, 
# audio, video) stored in heritage repositories.

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
  - ../metadata
  - ./DataServiceEndpoint

classes:
  FileAPI:
    is_a: DataServiceEndpoint
    class_uri: hc:FileAPI
    description: |
      File/asset retrieval API for downloading digital content.
      
      **Purpose:**
      
      Models endpoints that provide direct access to digital files
      (images, documents, audio, video, 3D models) stored in heritage repositories.
      
      **Distinction from Image Servers:**
      
      - **FileAPI**: Downloads original or derivative files as-is
      - **IIPImageServer**: Dynamic image delivery with zooming, tiling, region extraction
      
      Use FileAPI when you need:
      - Original/master files
      - Fixed-resolution derivatives
      - Non-image files (PDFs, audio, video, office documents)
      
      **Example - Nationaal Archief File API:**
      
      ```yaml
      file_api:
        endpoint_name: "Nationaal Archief File API"
        base_url: "https://service.archief.nl/gaf/api/file/v1/"
        url_pattern: "{base_url}{uuid}/{level}/{format}"
        version: "v1"
        supported_levels:
          - MASTER
          - HIGH
          - MEDIUM
          - LOW
          - THUMBNAIL
        supported_formats:
          - image/jpeg
          - image/png
          - application/pdf
        max_file_size_mb: 500
        supports_range_requests: true
        example_url: "https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg"
      ```
      
      **Use Cases:**
      
      1. **Download master files**: Archival-quality preservation copies
      2. **Generate derivatives**: Request specific size/format
      3. **Batch harvesting**: Download all files for a record
      4. **Streaming**: Audio/video delivery
      
      **See Also:**
      
      - Content-Disposition header for filename hints
      - HTTP Range requests (RFC 7233) for partial downloads
    
    attributes:
      base_url:
        slot_uri: dcat:endpointURL
        description: |
          Base URL for file retrieval.
          
          Individual files are accessed by appending identifiers.
          
          Example: "https://service.archief.nl/gaf/api/file/v1/"
        range: uri
        required: true
      
      url_pattern:
        slot_uri: hydra:template
        description: |
          URL pattern for constructing file requests.
          
          Use {placeholders} for dynamic parts:
          - {uuid}: File identifier
          - {level}: Quality level (master, high, low, thumbnail)
          - {format}: File format (jpeg, png, pdf)
          
          Example: "{base_url}{uuid}/{level}/{format}"
        range: string
      
      identifier_type:
        slot_uri: dcterms:identifier
        description: |
          Type of identifier used to request files.
          
          Values: UUID, HANDLE, DOI, ARK, LOCAL_ID, FILENAME
        range: string
      
      supported_levels:
        slot_uri: schema:encodingFormat
        description: |
          Quality/resolution levels available.
          
          Common levels:
          - MASTER/ORIGINAL: Archival master file
          - HIGH: High-resolution derivative
          - MEDIUM: Medium resolution (web-suitable)
          - LOW: Low resolution (fast loading)
          - THUMBNAIL: Small preview image
          
          Example: ["MASTER", "HIGH", "MEDIUM", "LOW", "THUMBNAIL"]
        range: string
        multivalued: true
      
      supported_formats:
        slot_uri: dcterms:format
        description: |
          File formats (MIME types) available for download.
          
          May vary by content type and level.
          
          Example:
          - Images: ["image/jpeg", "image/png", "image/tiff"]
          - Documents: ["application/pdf", "application/xml"]
          - Audio: ["audio/mpeg", "audio/wav"]
          - Video: ["video/mp4", "video/webm"]
        range: string
        multivalued: true
        required: true
      
      max_file_size_mb:
        slot_uri: schema:contentSize
        description: |
          Maximum file size available for download (in MB).
          
          Larger files may require special access or batch delivery.
          
          Example: 500
        range: integer
      
      typical_file_size_mb:
        slot_uri: schema:contentSize
        description: |
          Typical file size for most downloads (in MB).
          
          Helps clients estimate download times.
          
          Example: 10
        range: integer
      
      supports_range_requests:
        slot_uri: schema:additionalProperty
        description: |
          Whether HTTP Range requests are supported (RFC 7233).
          
          Enables:
          - Resumable downloads
          - Partial content retrieval
          - Streaming
          
          Check for Accept-Ranges: bytes header.
        range: boolean
      
      supports_streaming:
        slot_uri: schema:additionalProperty
        description: |
          Whether the API supports media streaming.
          
          Relevant for audio/video content.
          Enables progressive playback without full download.
        range: boolean
      
      content_disposition:
        slot_uri: schema:additionalProperty
        description: |
          Content-Disposition header behavior.
          
          Values:
          - INLINE: Browser displays content
          - ATTACHMENT: Browser downloads file
          - CONFIGURABLE: Client can request either
        range: ContentDispositionEnum
      
      filename_in_url:
        slot_uri: schema:additionalProperty
        description: |
          Whether original filename is included in URL.
          
          Some APIs include filename for better download naming:
          /api/file/v1/uuid/original.tif
        range: boolean
      
      supports_batch_download:
        slot_uri: schema:additionalProperty
        description: |
          Whether batch/bulk download is supported.
          
          May provide ZIP archives or async batch jobs.
        range: boolean
      
      batch_download_format:
        slot_uri: dcterms:format
        description: |
          Format for batch downloads.
          
          Example: "application/zip"
        range: string
      
      thumbnail_dimensions:
        slot_uri: schema:width
        description: |
          Dimensions of thumbnail images (if thumbnail level available).
          
          Format: "WIDTHxHEIGHT"
          
          Example: "150x150"
        range: string
      
      watermark_applied:
        slot_uri: schema:additionalProperty
        description: |
          Whether watermarks are applied to downloaded files.
          
          May vary by access level or file type.
        range: boolean
      
      access_restrictions:
        slot_uri: dcterms:accessRights
        description: |
          Access restrictions on file downloads.
          
          Examples:
          - "Public access to all levels"
          - "Master files require authentication"
          - "Some collections IP-restricted"
        range: string
      
      example_url:
        slot_uri: schema:workExample
        description: |
          Example URL for file download.
          
          Example: "https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg"
        range: uri
    
    slot_usage:
      protocol:
        # Note: Cannot use equals_string with enum range - validation enforced by enum
        description: File APIs use REST protocol for downloads (DataServiceProtocolEnum.REST).
      
      authentication_required:
        description: |
          Master files often require authentication.
          Thumbnails and low-res typically public.
    
    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"

enums:
  ContentDispositionEnum:
    description: |
      HTTP Content-Disposition header behavior options.
    permissible_values:
      INLINE:
        description: |
          Content displayed inline in browser.
          
          Header: Content-Disposition: inline
          
          Browser attempts to render (images, PDFs).
      ATTACHMENT:
        description: |
          Content downloaded as attachment.
          
          Header: Content-Disposition: attachment; filename="example.pdf"
          
          Browser prompts for download.
      CONFIGURABLE:
        description: |
          Client can request either behavior.
          
          Usually via query parameter: ?download=true