563 lines
18 KiB
YAML
563 lines
18 KiB
YAML
# 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.
|