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 - ../slots/protocol - ../slots/specificity_annotation - ../slots/has_or_had_score - ./SpecificityAnnotation - ./TemplateSpecificityScore - ./TemplateSpecificityType - ./TemplateSpecificityTypes - ../enums/ContentDispositionEnum 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_or_had_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" 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 has_or_had_format: 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: uriorcurie 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 has_or_had_access_restriction: 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 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: - specificity_annotation - has_or_had_score annotations: specificity_score: 0.1 specificity_rationale: Generic utility class/slot created during migration custodian_types: "['*']" custodian_types_rationale: Universal utility concept