API Reference

API Design Principles

The DOCiD™ API is built following RESTful principles with comprehensive support for metadata management, persistent identifiers, and scholarly communication workflows.

Standard Response Format

All API responses follow a consistent structure for both success and error cases, facilitating predictable client-side handling.

{
    "status": "success",
    "data": {
        // Response payload with requested data
        "publication": {
            "id": 1,
            "document_title": "Research Publication Title",
            "doi": "10.5555/docid.example.001"
        }
    },
    "message": "Operation completed successfully",
    "timestamp": "2024-01-15T10:30:00Z"
}

{
    "status": "error",
    "error": "Validation failed for publication data",
    "code": "VALIDATION_ERROR",
    "details": {
        "field_errors": {
            "document_title": "Title is required and cannot be empty",
            "creators": "At least one creator must be specified"
        },
        "request_id": "req_abc123def456"
    },
    "timestamp": "2024-01-15T10:30:00Z"
}

Authentication Endpoints

Authentication system supporting both traditional email/password and social OAuth providers (Google, ORCID, GitHub) with JWT-based session management.

POST /api/v1/auth/login
Content-Type: application/json

{
    "email": "amara.okonkwo@uct.ac.za",
    "password": "SecurePass123!"
}

{
    "status": "success",
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expires_in": 3600,
        "user": {
            "user_id": 1,
            "full_name": "Dr. Amara Okonkwo",
            "email": "amara.okonkwo@uct.ac.za",
            "role": "user",
            "orcid_id": "0000-0002-1234-5678",
            "affiliation": "University of Cape Town",
            "ror_id": "https://ror.org/01ggx4157"
        }
    },
    "message": "Authentication successful"
}

{
    "email": "user@example.com",
    "full_name": "John Doe",
    "password": "secure_password",
    "orcid_id": "0000-0000-0000-0000",
    "affiliation": "University Name"
}

{
    "email": "user@example.com"
}

Publication Management Endpoints

Comprehensive publication lifecycle management including creation, metadata management, identifier assignment, and external service integration based on the Publications model.

{
    "title": "Research Paper Title",
    "abstract": "Paper abstract...",
    "resource_type_id": 1,
    "publication_type_id": 1,
    "creators": [
        {
            "creator_name": "John Doe",
            "orcid_id": "0000-0000-0000-0000",
            "role_id": 1,
            "affiliation": "University Name"
        }
    ],
    "organizations": [
        {
            "organization_name": "University Name",
            "ror_id": "ror_id_here",
            "country": "Country Name"
        }
    ],
    "funders": [
        {
            "funder_name": "Grant Agency",
            "grant_number": "GRANT-2023-001",
            "award_amount": 50000.00
        }
    ]
}

{
    "publications": [
        {
            "id": 1,
            "title": "Research Paper Title",
            "docid": "DOCID.001",
            "doi": "10.5555/example.doi",
            "resource_type": "dataset",
            "creators": [...],
            "organizations": [...],
            "created_at": "2023-01-01T00:00:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "pages": 5,
        "total": 50,
        "limit": 10
    }
}

Comments System Endpoints

Hierarchical commenting system supporting threaded discussions, moderation, and engagement tracking based on the PublicationComments model with parent-child relationships.

{
    "publication_id": 1,
    "total_comments": 5,
    "comments": [
        {
            "id": 1,
            "user_id": 1,
            "user_name": "John Doe",
            "comment_text": "Great research work!",
            "comment_type": "general",
            "status": "active",
            "likes_count": 3,
            "created_at": "2023-01-01T10:00:00Z",
            "replies": [
                {
                    "id": 2,
                    "user_id": 2,
                    "user_name": "Jane Smith",
                    "comment_text": "I agree, very insightful.",
                    "parent_comment_id": 1,
                    "created_at": "2023-01-01T11:00:00Z"
                }
            ]
        }
    ]
}

{
    "user_id": 1,
    "comment_text": "This is a great contribution to the field.",
    "comment_type": "review"
}

{
    "user_id": 1,
    "comment_text": "Thank you for the feedback!",
    "comment_type": "general",
    "parent_comment_id": 1
}

{
    "user_id": 1,
    "comment_text": "Updated comment text"
}

{
    "user_id": 1
}

{
    "publication_id": 1,
    "statistics": {
        "total_comments": 10,
        "top_level_comments": 7,
        "replies": 3,
        "unique_commenters": 5,
        "total_likes": 15,
        "comment_types": {
            "general": 6,
            "review": 3,
            "question": 1
        }
    }
}

External Service Integration Endpoints

Integration endpoints for scholarly communication infrastructure including Crossref, ROR, ORCID, CORDRA, and CSTR services for metadata enrichment and identifier resolution.

{
    "query": "machine learning",
    "rows": 10,
    "sort": "relevance"
}

Verification & Integrity Endpoints

Public, unauthenticated. Full detail in Integrity & Checksums.

Returns 400 without an identifier, 404 when no such DOCiD exists, and 410 when the record has been retired.

Subsystem Endpoints

Endpoint groups added since v1.0 of this documentation. Only the integration surface is listed; administrative routes are deliberately omitted.

Local Contexts

Research resources (RRID)

Resolved RRID metadata appears in publication responses as research_resources[], and is also merged inline into each attached document and organization entry.

Versioning

Versions form a flat chain, not a tree: versioning a version reparents to the root. Each version is an independent record with its own DOCiD, its own files, and its own checksums.

Tenant branding