# Data Service Endpoint - Abstract Base Class for API Endpoints # Represents API service endpoints exposed by heritage digital platforms # # This is an ABSTRACT class - use concrete subclasses: # - OAIPMHEndpoint (metadata harvesting) # - SearchAPI (search/query) # - METSAPI (METS document retrieval) # - FileAPI (file/asset retrieval) # - IIPImageServer (image serving) # - EADDownload (finding aid download) # # Ontology Alignment: # - Primary: dcat:DataService (DCAT 3) # - Secondary: schema:WebAPI, hydra:ApiDocumentation 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 classes: DataServiceEndpoint: abstract: true class_uri: dcat:DataService description: | Abstract base class for API service endpoints exposed by heritage digital platforms. **Purpose:** Models the technical API endpoints discovered at heritage institutions, enabling: - Machine-readable discovery of available APIs - Integration with aggregation platforms - Automated harvesting and synchronization - Developer documentation **DCAT 3 Alignment:** Maps to `dcat:DataService` which represents: - "A collection of operations that provides access to one or more datasets or data processing functions" - Has endpoint URL (dcat:endpointURL) - Has endpoint description/documentation (dcat:endpointDescription) - May serve one or more datasets (dcat:servesDataset) **Subclasses:** | Class | Protocol | Purpose | |-------|----------|---------| | OAIPMHEndpoint | OAI-PMH | Metadata harvesting | | SearchAPI | REST/JSON | Search and discovery | | METSAPI | REST/XML | METS document retrieval | | FileAPI | REST | File/asset download | | IIPImageServer | IIP/IIIF | Image serving | | EADDownload | HTTP | EAD finding aid export | **Example - Nationaal Archief APIs:** ```yaml digital_platform: platform_name: "Nationaal Archief Website" data_service_endpoints: - endpoint_type: OAIPMHEndpoint endpoint_url: "https://www.nationaalarchief.nl/onderzoeken/oai-pmh" protocol: OAI-PMH - endpoint_type: SearchAPI endpoint_url: "https://www.nationaalarchief.nl/onderzoeken/api/zoeken" protocol: REST response_formats: ["application/json"] - endpoint_type: IIPImageServer endpoint_url: "https://service.archief.nl/iipsrv" protocol: IIP ``` **Provenance:** DataServiceEndpoint instances MUST include discovery provenance: - When the endpoint was discovered - How it was discovered (web scrape, documentation, API testing) - Verification status 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 protocol: slot_uri: dcterms:conformsTo description: | Protocol or standard the endpoint implements. Values from DataServiceProtocolEnum: - OAI_PMH: Open Archives Initiative Protocol for Metadata Harvesting - REST: RESTful HTTP API - SOAP: SOAP web services - GRAPHQL: GraphQL API - SPARQL: SPARQL endpoint - IIIF_IMAGE: IIIF Image API - IIIF_PRESENTATION: IIIF Presentation API - IIP: Internet Imaging Protocol - ZOOMIFY: Zoomify tile protocol - SRU: Search/Retrieve via URL range: DataServiceProtocolEnum required: true response_formats: slot_uri: dcterms:format description: | MIME types of response formats supported by this endpoint. Examples: - ["application/json"] - ["application/xml", "text/xml"] - ["image/jpeg", "image/png", "image/tiff"] - ["application/ld+json", "text/turtle"] range: string multivalued: true authentication_required: slot_uri: schema:authenticationType description: | Whether authentication is required to access this endpoint. Values: - true: API key, OAuth, or other authentication required - false: Public/anonymous access allowed - null: Unknown If true, see authentication_method for details. range: boolean 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/" 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.