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 - ../slots/authentication_required - ../slots/specificity_annotation - ../slots/template_specificity - ./SpecificityAnnotation - ./TemplateSpecificityScores classes: DataServiceEndpoint: abstract: true class_uri: dcat:DataService slots: - authentication_required - protocol - response_format - specificity_annotation - template_specificity 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 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 authentication_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. **Instance vs Type Architecture:** This slot links an INSTANCE (DataServiceEndpoint) to its TYPE classification (DataServiceEndpointType), following the same architectural pattern as Custodian/CustodianType. ``` DataServiceEndpoint (INSTANCE) DataServiceEndpointType (TYPE) ├── endpoint_url ├── protocol_name ├── status ├── protocol_version ├── authentication_required ├── specification_url └── endpoint_type ────────────────►└── typical_response_formats ``` **Why Both `protocol` and `endpoint_type`?** - `protocol` (enum): Simple string classification for quick filtering - `endpoint_type` (class reference): Rich type metadata with SKOS hierarchy, specification URLs, and semantic relationships **Example:** ```yaml data_service_endpoint: endpoint_id: "https://nde.nl/hc/endpoint/na-oai-pmh" endpoint_url: "https://www.nationaalarchief.nl/onderzoeken/oai-pmh" protocol: OAI_PMH # Simple enum (DataServiceProtocolEnum) endpoint_type: OAIPMHEndpointType # Rich type (DataServiceEndpointType subclass) ``` This pattern mirrors: - `custodian_type` enum + `CustodianType` class on `Custodian` - `platform_type` enum + `DigitalPlatformType` class on `DigitalPlatform` 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/ slot_usage: specificity_annotation: range: SpecificityAnnotation inlined: true template_specificity: range: TemplateSpecificityScores inlined: true enums: DataServiceProtocolEnum: description: | Protocols and standards implemented by data service endpoints. permissible_values: OAI_PMH: description: | Open Archives Initiative Protocol for Metadata Harvesting. Standard for harvesting metadata from repositories. Specification: http://www.openarchives.org/OAI/openarchivesprotocol.html REST: description: | RESTful HTTP API. Uses HTTP methods (GET, POST, etc.) with JSON/XML responses. SOAP: description: | SOAP web services. XML-based protocol with WSDL service description. GRAPHQL: description: | GraphQL API. Query language for APIs. SPARQL: description: | SPARQL Protocol and RDF Query Language. For querying RDF triple stores. IIIF_IMAGE: description: | IIIF Image API. International Image Interoperability Framework Image API. Specification: https://iiif.io/api/image/ IIIF_PRESENTATION: description: | IIIF Presentation API. For describing structure and layout of compound digital objects. Specification: https://iiif.io/api/presentation/ IIIF_CONTENT_SEARCH: description: | IIIF Content Search API. For searching within annotations. Specification: https://iiif.io/api/search/ IIIF_CHANGE_DISCOVERY: description: | IIIF Change Discovery API. For discovering changes in IIIF resources. Specification: https://iiif.io/api/discovery/ IIP: description: | Internet Imaging Protocol. Tile-based image delivery protocol. Common implementations: IIPImage server. ZOOMIFY: description: | Zoomify tile protocol. Proprietary but widely-supported tiling format. DEEPZOOM: description: | Microsoft Deep Zoom. Tile-based image format for Seadragon viewers. SRU: description: | Search/Retrieve via URL. Standard search protocol from Library of Congress. Specification: http://www.loc.gov/standards/sru/ Z39_50: description: | ANSI/NISO Z39.50 protocol. Library search and retrieval protocol. ATOM: description: | Atom Syndication Format. XML-based feed format for content syndication. RSS: description: | RSS (Really Simple Syndication). XML-based feed format. OPENSEARCH: description: | OpenSearch protocol. Collection of simple formats for sharing search results. Specification: https://opensearch.org/ WEBDAV: description: | WebDAV (Web Distributed Authoring and Versioning). HTTP extension for collaborative editing. FTP: description: | File Transfer Protocol. For bulk file downloads. AuthenticationMethodEnum: description: | Authentication methods for accessing API endpoints. permissible_values: NONE: description: No authentication required (public access) API_KEY: description: | API key authentication. Key provided in HTTP header (e.g., X-API-Key) or query parameter. API_KEY_HEADER: description: API key in HTTP header API_KEY_QUERY: description: API key in URL query parameter OAUTH2: description: | OAuth 2.0 authentication. Token-based authentication with authorization flow. OAUTH1: description: OAuth 1.0a authentication BASIC: description: | HTTP Basic Authentication. Username/password in Authorization header. BEARER_TOKEN: description: | Bearer token authentication. JWT or opaque token in Authorization header. IP_WHITELIST: description: | IP address whitelist. Access restricted to specific IP ranges. INSTITUTIONAL: description: | Institutional login. Shibboleth, SAML, or similar federated authentication. CLIENT_CERTIFICATE: description: | Client certificate authentication. TLS/SSL client certificates. DIGEST: description: HTTP Digest Authentication EndpointStatusEnum: description: | Operational status of an API endpoint. permissible_values: ACTIVE: description: | Endpoint is operational and accepting requests. DEPRECATED: description: | Endpoint works but is deprecated. Will be removed in future - migrate to new endpoint. BETA: description: | Endpoint in testing/beta phase. May change without notice. ALPHA: description: | Endpoint in early alpha testing. Not recommended for production use. OFFLINE: description: | Endpoint currently unavailable. May be temporary maintenance or permanent shutdown. MAINTENANCE: description: | Endpoint temporarily offline for maintenance. UNKNOWN: description: | Status not verified. Needs testing to determine current status.