OAI-PMH Adapter Guide
Deploy a metadata harvesting endpoint for repository integration.
Quick Deployment
Get your OAI-PMH endpoint running in minutes
# Deploy OAI-PMH adapter
git clone https://github.com/nobleid/oai-pmh-adapter
cd oai-pmh-adapter
# Configure environment
cp .env.example .env
# Edit .env with your NOBLEID_API_KEY
# Deploy to your server
docker build -t nobleid-oai .
docker run -p 8080:8080 -d nobleid-oai
# Test endpoint
curl "http://localhost:8080/oai?verb=Identify"Requirements
- • Docker or Node.js 18+
- • NOBLEID API key
- • Public domain/subdomain
- • SSL certificate (recommended)
Configuration
Environment variables and customization options
# .env configuration
NOBLEID_API_KEY=your_api_key_here
REPOSITORY_NAME=Your Institution Repository
ADMIN_EMAIL=admin@example.org
BASE_URL=https://oai.example.org
# Optional: Filter by organization
ORGANIZATION_FILTER=example-university
# Optional: Custom metadata prefix
METADATA_PREFIX=oai_dc
# Optional: Set resumption token TTL
RESUMPTION_TOKEN_TTL=3600Advanced Options
- •
ORGANIZATION_FILTER- Limit to specific institution - •
RESUMPTION_TOKEN_TTL- Token expiration time - •
MAX_RECORDS_PER_REQUEST- Pagination size - •
ENABLE_SETS- Enable set-based harvesting
Dublin Core Mapping
How NOBLEID metadata maps to Dublin Core fields
<!-- Dublin Core mapping -->
<oai_dc:dc>
<dc:identifier>ark:/nobleid/20092025/7X9K2Q</dc:identifier>
<dc:identifier>https://doi.org/10.1000/182</dc:identifier>
<dc:title>Example Research Paper</dc:title>
<dc:creator>Smith, Jane</dc:creator>
<dc:subject>Computer Science</dc:subject>
<dc:description>This paper explores...</dc:description>
<dc:publisher>Example Journal</dc:publisher>
<dc:date>2025-01-15</dc:date>
<dc:type>Text</dc:type>
<dc:format>application/pdf</dc:format>
<dc:language>en</dc:language>
<dc:rights>© 2025 Authors</dc:rights>
</oai_dc:dc>Field Mapping
NOBLEID Field
Dublin Core
ark
dc:identifier
title
dc:title
authors[].name
dc:creator
abstract
dc:description
subjects[]
dc:subject
publisher_name
dc:publisher
published_date
dc:date
Supported Verbs
Complete OAI-PMH 2.0 protocol implementation
# OAI-PMH verbs supported:
# Identify - Repository information
curl "https://oai.example.org/oai?verb=Identify"
# ListMetadataFormats - Available formats
curl "https://oai.example.org/oai?verb=ListMetadataFormats"
# ListSets - Available sets (organizations)
curl "https://oai.example.org/oai?verb=ListSets"
# ListIdentifiers - List all identifiers
curl "https://oai.example.org/oai?verb=ListIdentifiers&metadataPrefix=oai_dc"
# ListRecords - List all records
curl "https://oai.example.org/oai?verb=ListRecords&metadataPrefix=oai_dc"
# GetRecord - Get specific record
curl "https://oai.example.org/oai?verb=GetRecord&identifier=ark:/nobleid/20092025/7X9K2Q&metadataPrefix=oai_dc"Protocol Features
- ✓ Resumption tokens for large result sets
- ✓ Selective harvesting by date range
- ✓ Set-based harvesting by organization
- ✓ Deleted record tracking
- ✓ Multiple metadata formats
- ✓ Error handling and validation
Testing & Validation
Verify your OAI-PMH endpoint is working correctly
Validation Tools
Common Issues
- • Ensure SSL certificate is valid
- • Check API key permissions
- • Verify XML encoding (UTF-8)
- • Test resumption token handling
- • Validate Dublin Core compliance