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# imports: - linkml:types - ../metadata - ./DataServiceEndpointType - ../slots/protocol - ../slots/response_format # REMOVED 2026-01-15: ../slots/authentication_required - migrated to is_or_was_required - ../slots/is_or_was_required - ../slots/specificity_annotation - ../slots/has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17) - ./SpecificityAnnotation - ./TemplateSpecificityScore # was: TemplateSpecificityScores - migrated per Rule 53 (2026-01-17) - ./TemplateSpecificityType - ./TemplateSpecificityTypes - ../enums/DataServiceProtocolEnum - ../enums/AuthenticationMethodEnum - ../enums/EndpointStatusEnum classes: DataServiceEndpoint: abstract: true class_uri: dcat:DataService slots: # REMOVED 2026-01-15: authentication_required - migrated to is_or_was_required - is_or_was_required - protocol - response_format - specificity_annotation - has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17) description: "Abstract base class for API service endpoints exposed by heritage digital platforms.\n\n**Purpose:**\n\n\ Models 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 attributes: endpoint_id: identifier: true slot_uri: dcterms:identifier description: 'Unique identifier for this data service endpoint. Recommended format: URI combining platform ID and service type. Example: "https://nde.nl/ontology/hc/endpoint/nationaalarchief-oai-pmh" ' range: uriorcurie required: true endpoint_name: slot_uri: schema:name description: 'Human-readable name for this endpoint. Examples: - "Nationaal Archief OAI-PMH Endpoint" - "Heritage Search API" - "Image Server (IIP)" ' range: string required: true endpoint_url: slot_uri: dcat:endpointURL description: 'Base URL of the service endpoint. DCAT: dcat:endpointURL - "The root location or primary endpoint of the service" This is the URL that clients use to access the service. Examples: - "https://www.nationaalarchief.nl/onderzoeken/oai-pmh" - "https://api.europeana.eu/record/v2/" - "https://service.archief.nl/iipsrv" ' range: uri required: true endpoint_description_url: slot_uri: dcat:endpointDescription description: 'URL to machine-readable API documentation. DCAT: dcat:endpointDescription - "A description of the service end-point" May be: - OpenAPI/Swagger specification (JSON/YAML) - OAI-PMH Identify response - WSDL document - Human-readable documentation page Examples: - "https://api.example.org/openapi.json" - "https://www.nationaalarchief.nl/onderzoeken/oai-pmh?verb=Identify" ' range: uri authentication_method: slot_uri: schema:potentialAction description: 'Authentication method required (if is_or_was_required is true). Values from AuthenticationMethodEnum: - NONE: No authentication - API_KEY: API key in header or query parameter - OAUTH2: OAuth 2.0 - BASIC: HTTP Basic Authentication - IP_WHITELIST: IP address whitelist - INSTITUTIONAL: Institutional login (Shibboleth, etc.) ' range: AuthenticationMethodEnum cors_enabled: slot_uri: schema:additionalProperty description: 'Whether CORS (Cross-Origin Resource Sharing) is enabled. Important for browser-based JavaScript applications: - true: Cross-origin requests allowed - false: Same-origin only - null: Unknown ' range: boolean rate_limit: slot_uri: schema:rateValue description: 'Rate limit description if applicable. Free-text description of rate limiting policy. Examples: - "100 requests per minute" - "1000 requests per day per API key" - "No limit" - "Unknown" ' range: string documentation_url: slot_uri: schema:documentation description: 'URL to human-readable documentation. This is separate from endpoint_description_url which is machine-readable. Examples: - "https://pro.europeana.eu/resources/apis/record" - "https://www.nationaalarchief.nl/onderzoeken/handleiding/api" ' range: uri status: slot_uri: schema:serverStatus description: 'Operational status of the endpoint. Values from EndpointStatusEnum: - ACTIVE: Endpoint is operational - DEPRECATED: Endpoint works but will be removed - BETA: Endpoint in testing/beta - OFFLINE: Endpoint currently unavailable - UNKNOWN: Status not verified ' range: EndpointStatusEnum last_verified: slot_uri: schema:dateModified description: 'Date when this endpoint was last verified to be operational. ISO 8601 date format. Example: "2025-12-14" ' range: date serves_dataset: slot_uri: dcat:servesDataset description: 'Dataset(s) that this service provides access to. DCAT: dcat:servesDataset - "A collection of data that this data service can distribute" References to DCAT Dataset identifiers or descriptions. ' range: uriorcurie multivalued: true version: slot_uri: schema:version description: 'Version of the API or service. Examples: - "v2" - "1.0.0" - "2023-01" ' range: string discovery_provenance: slot_uri: dcterms:provenance description: 'Provenance information about how this endpoint was discovered. Should include: - Discovery date - Discovery method (documentation, web scrape, API testing) - Verification status Free-text or structured provenance note. ' range: string endpoint_type: slot_uri: dcterms:type description: "Classification of this endpoint from the DataServiceEndpointType taxonomy.\n\n**Instance vs Type Architecture:**\n\ \nThis slot links an INSTANCE (DataServiceEndpoint) to its TYPE classification\n(DataServiceEndpointType), following\ \ the same architectural pattern as\nCustodian/CustodianType.\n\n```\nDataServiceEndpoint (INSTANCE) DataServiceEndpointType\ \ (TYPE)\n├── endpoint_url ├── protocol_name\n├── status ├── protocol_version\n\ ├── is_or_was_required ├── specification_url\n└── endpoint_type ────────────────►└── has_or_had_format\n\ ```\n\n**Why Both `protocol` and `endpoint_type`?**\n\n- `protocol` (enum): Simple string classification for quick\ \ filtering\n- `endpoint_type` (class reference): Rich type metadata with SKOS hierarchy,\n specification URLs,\ \ and semantic relationships\n\n**Example:**\n\n```yaml\ndata_service_endpoint:\n endpoint_id: \"https://nde.nl/hc/endpoint/na-oai-pmh\"\ \n endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\n protocol: OAI_PMH \ \ # Simple enum (DataServiceProtocolEnum)\n endpoint_type: OAIPMHEndpointType # Rich type (DataServiceEndpointType\ \ subclass)\n```\n\nThis pattern mirrors:\n- `custodian_type` enum + `CustodianType` class on `Custodian`\n- `platform_type`\ \ enum + `DigitalPlatformType` class on `DigitalPlatform`\n" range: DataServiceEndpointType required: false comments: - Links to DataServiceEndpointType taxonomy for rich type metadata - Complements the simple `protocol` enum with class-based classification - 'Follows Instance/Type pattern: Custodian→CustodianType, DigitalPlatform→DigitalPlatformType' 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/