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=3600

Advanced 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

OAI Repository Explorer OAI-PMH Validator

Common Issues

• Ensure SSL certificate is valid
• Check API key permissions
• Verify XML encoding (UTF-8)
• Test resumption token handling
• Validate Dublin Core compliance