openapi: "3.0.3"
info:
  title: "Health Impact in Venezuela (2024–2025): Key Indicators, Factors and Disease Data — API Specification"
  description: |
    OpenAPI specification for accessing this dataset via the Zenodo REST API.
    Dataset DOI: 10.5281/zenodo.19150895
    This document describes how to programmatically access, query, and download
    the files in this dataset using the Zenodo public API.
  version: "1.0.3"
  contact:
    name: "de la Serna, Juan Moisés"
    url: "https://orcid.org/0000-0002-8401-8018"
  license:
    name: "CC BY 4.0"
    url: "https://creativecommons.org/licenses/by/4.0/"

servers:
  - url: "https://zenodo.org/api"
    description: "Zenodo REST API (production)"

tags:
  - name: "records"
    description: "Access dataset record metadata and files"
  - name: "files"
    description: "Download individual data files"

paths:
  /records/19150895:
    get:
      tags: [records]
      summary: "Get dataset metadata"
      description: "Returns full metadata for this dataset version (v1.0.3)"
      parameters:
        - name: access_token
          in: query
          required: false
          schema:
            type: string
          description: "Personal access token (for restricted records only)"
      responses:
        "200":
          description: "Dataset metadata in JSON format"
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 19150895
                  doi:
                    type: string
                    example: "10.5281/zenodo.19150895"
                  metadata:
                    type: object
                    properties:
                      title:
                        type: string
                      description:
                        type: string
                      keywords:
                        type: array
                        items:
                          type: string
                      version:
                        type: string
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        size:
                          type: integer
                        checksum:
                          type: string
        "404":
          description: "Record not found"

  /records/19150895/files:
    get:
      tags: [files]
      summary: "List all files in this dataset"
      description: "Returns a list of all files available in this dataset version"
      responses:
        "200":
          description: "List of files"
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          description: "Filename"
                        size:
                          type: integer
                          description: "File size in bytes"
                        checksum:
                          type: string
                          description: "MD5 checksum"
                        links:
                          type: object
                          properties:
                            content:
                              type: string
                              format: uri
                              description: "Direct download URL"

  /records/19150895/files/health_indicators_venezuela_2020_2025.csv/content:
    get:
      tags: [files]
      summary: "Download health_indicators_venezuela_2020_2025.csv"
      description: "Direct download of the CSV data file: health_indicators_venezuela_2020_2025.csv"
      responses:
        "200":
          description: "CSV file content"
          content:
            text/csv:
              schema:
                type: string
                format: binary

components:
  schemas:
    DataRecord:
      type: object
      description: "Represents a row in the dataset"
      properties:
        country:
          type: string
          description: "Country name"
        year:
          type: integer
          description: "Reference year"
        value:
          type: number
          nullable: true
          description: "Measured value"
        indicator:
          type: string
          description: "Indicator name"
        source:
          type: string
          description: "Data source"

externalDocs:
  description: "Zenodo REST API Documentation"
  url: "https://developers.zenodo.org"
