OJS REST API: Programmatic Ingestion & Data Extraction
Comprehensive technical manual for the OJS REST API. Covers API key generation, Swagger documentation, submission ingestion endpoints, and Python automation scripts.
Real Problem
Institutions running centralized research repositories struggle to manually re-enter publication data into OJS, leading to duplicate entry and synchronized data lag.
Practical Solution
Harness the native OJS REST API: generate secure API secret tokens, execute authenticated JSON requests, automate manuscript submissions, and extract real-time publication analytics.
The API-Driven Architecture of Modern Scholarly Portals
As academic institutions modernize their digital infrastructure, Open Journal Systems is no longer an isolated island. It must communicate bidirectionally with:
- Current Research Information Systems (CRIS / Pure / Symplectic Elements).
- Institutional Repositories (DSpace / EPrints / Fedora).
- University Faculty Activity Reporting and HR Databases.
- Automated typesetting and XML publishing pipelines.
The PKP REST API provides a standards-compliant, JSON-based interface conforming to RESTful conventions.
Step 1: Enabling API Key Generation in config.inc.php
Open config.inc.php and verify the [security] section:
[security]
api_key_secret = "YourRandomCryptographicKey32CharactersLong"
If this directive is empty or missing, API keys cannot be validated.
Step 2: Generating an API Secret Key
1. Log in to OJS as an Administrator or Journal Manager.
2. Click your user profile in the top right corner and navigate to "API Key".
3. Click "Generate API Key".
4. Copy the secret token. This key inherits all permissions of your administrative user account.
Step 3: Core API Endpoints Overview
All API endpoints follow the URL structure:
https://journal.institution.edu/index.php/{journal_path}/api/v1/{endpoint}
Key Endpoints:
- GET /api/v1/submissions: Retrieve list of submissions (filtered by status, stage, or category).
- GET /api/v1/submissions/{id}: Retrieve detailed metadata, authors, and galleys for a specific article.
- POST /api/v1/submissions: Programmatically create a new submission.
- GET /api/v1/issues: List all published issues and tables of contents.
- GET /api/v1/users: Search and retrieve user accounts and roles.
Step 4: Practical Python Automation Example
The following Python script extracts all published articles from a target journal and exports their titles, DOIs, and author lists to JSON:
import requests
BASE_URL = "https://journal.institution.edu/index.php/jar/api/v1"
API_TOKEN = "your_secret_api_token_here"
headers = {
"Authorization": f"Bearer {API_TOKEN}"
}
params = {
"status": 3, # STATUS_PUBLISHED
"count": 50
}
response = requests.get(f"{BASE_URL}/submissions", headers=headers, params=params)
if response.status_code == 200:
articles = response.json().get('items', [])
for article in articles:
pub = article.get('publications', [{}])[0]
print(f"Title: {pub.get('fullTitle', {}).get('en_US')}")
print(f"DOI: {pub.get('doi')}")
print("-" * 40)
else:
print(f"API Error: {response.status_code} - {response.text}")
Step-by-Step Action Plan
Enable REST API in config.inc.php
Verify that api_key_secret is configured in config.inc.php and REST endpoints are accessible.
Generate User API Secret Token
In User Profile > API Key, generate a persistent authorization secret token for API authentication.
Explore Swagger API Documentation
Navigate to /index.php/{journal}/api/v1/ to view live interactive OpenAPI / Swagger endpoint documentation.
Execute Authenticated HTTP Requests
Send requests with Authorization: Bearer {token} or ?apiToken={token} query parameters.
Build Automated Python Ingestion Script
Write Python or Node.js daemons to programmatically fetch published articles or ingest new submissions.
Questions People Usually Ask
What version of OJS introduced the native REST API?
The REST API was introduced in OJS 3.1 and substantially expanded in OJS 3.3, 3.4, and 3.5 to encompass full CRUD operations across submissions, issues, contexts, and users.
Can an external script submit a new article via the REST API?
Yes! By sending a POST request to /api/v1/submissions, an external application can create a submission, assign metadata, upload manuscript files, and transition the paper to the review queue.
Is the OJS REST API rate-limited?
Default OJS does not enforce hard rate limits in code; rate limiting should be managed at the Nginx or Cloudflare reverse proxy level to protect the server from abuse.
Need Enterprise API Integrations for OJS?
AcademiaTech builds high-speed data connectors and automated ingestion pipelines between OJS and institutional CRIS/ERP systems.