id: https://nde.nl/ontology/hc/class/DataServiceEndpoint
name: data_service_endpoint
title: DataServiceEndpoint 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/
  hydra: http://www.w3.org/ns/hydra/core#
  xsd: http://www.w3.org/2001/XMLSchema#
  prov: http://www.w3.org/ns/prov#
  crm: http://www.cidoc-crm.org/cidoc-crm/
  skos: http://www.w3.org/2004/02/skos/core#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  org: http://www.w3.org/ns/org#
imports:
  - linkml:types
  - ../enums/AuthenticationMethodEnum
  - ../enums/DataServiceProtocolEnum
  - ../enums/EndpointStatusEnum
  - ../metadata
  - ../slots/has_score
  - ../slots/has_url
  - ../slots/required
  - ../slots/has_format
classes:
  DataServiceEndpoint:
    abstract: true
    class_uri: dcat:DataService
    slots:
    - required
    - has_format
    - has_url
    - has_score
    description: "Abstract base class for API service endpoints exposed by heritage\
      \ digital platforms.\n\n**Purpose:**\n\nModels the technical API endpoints discovered\
      \ at heritage institutions, enabling:\n- Machine-readable discovery of available\
      \ APIs\n- Integration with aggregation platforms\n- Automated harvesting and\
      \ synchronization\n- Developer documentation\n\n**DCAT 3 Alignment:**\n\nMaps\
      \ to `dcat:DataService` which represents:\n- \"A collection of operations that\
      \ provides access to one or more datasets or data processing functions\"\n-\
      \ Has endpoint URL (dcat:endpointURL)\n- Has endpoint description/documentation\
      \ (dcat:endpointDescription)\n- May serve one or more datasets (dcat:servesDataset)\n\
      \n**Subclasses:**\n\n| Class | Protocol | Purpose |\n|-------|----------|---------|\n\
      | OAIPMHEndpoint | OAI-PMH | Metadata harvesting |\n| SearchAPI | REST/JSON\
      \ | Search and discovery |\n| METSAPI | REST/XML | METS document retrieval |\n\
      | FileAPI | REST | File/asset download |\n| IIPImageServer | IIP/IIIF | Image\
      \ serving |\n| EADDownload | HTTP | EAD finding aid export |\n\n**Example -\
      \ Nationaal Archief APIs:**\n\n```yaml\ndigital_platform:\n  platform_name:\
      \ \"Nationaal Archief Website\"\n  data_service_endpoints:\n    - endpoint_type:\
      \ OAIPMHEndpoint\n      endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\
      \n      protocol: OAI-PMH\n      \n    - endpoint_type: SearchAPI\n      endpoint_url:\
      \ \"https://www.nationaalarchief.nl/onderzoeken/api/zoeken\"\n      protocol:\
      \ REST\n      response_formats: [\"application/json\"]\n      \n    - endpoint_type:\
      \ IIPImageServer\n      endpoint_url: \"https://service.archief.nl/iipsrv\"\n\
      \      protocol: IIP\n```\n\n**Provenance:**\n\nDataServiceEndpoint instances\
      \ MUST include discovery provenance:\n- When the endpoint was discovered\n-\
      \ How it was discovered (web scrape, documentation, API testing)\n- Verification\
      \ status\n"
    exact_mappings:
    - dcat:DataService
    close_mappings:
    - schema:WebAPI
    - hydra:ApiDocumentation
    comments:
    - Abstract class - use concrete subclasses (OAIPMHEndpoint, SearchAPI, etc.)
    - Maps to DCAT 3 dcat:DataService for semantic interoperability
    - Required for modeling API infrastructure of heritage digital platforms
    see_also:
    - https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service
    - https://schema.org/WebAPI
    - https://www.hydra-cg.com/spec/latest/core/
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: '[''*'']'