# x-provenance:
#   generated: '2026-08-30'
#   method: probed
#   source: https://www.datafirst.uct.ac.za/dataportal/index.php/api/
#   x-operator: institution
#   note: >-
#     Reverse-engineered ONLY from live responses observed against the DataFirst
#     NADA catalog host on 2026-08-30. Every path, parameter and response field
#     below was returned by a real request. Nothing is inferred from NADA's
#     upstream documentation.
openapi: 3.0.3
info:
  title: DataFirst Microdata Catalog API (NADA)
  description: >-
    DataFirst is a University of Cape Town research unit and data service
    providing online access to survey and administrative microdata from South
    Africa and other African countries. Its open data portal runs the NADA
    (National Data Archive) cataloging application on UCT's own host,
    www.datafirst.uct.ac.za, and exposes a public, unauthenticated REST/JSON
    API over the catalog. This OpenAPI description was reverse-engineered from
    confirmed live responses on 2026-08-30 (582 studies returned by the catalog
    endpoint). Only paths and response fields actually observed in live
    responses are documented here. The service is operated by UCT; the NADA
    application itself is open-source software from the International Household
    Survey Network.
  version: '1.1'
  contact:
    name: DataFirst, University of Cape Town
    url: https://www.datafirst.uct.ac.za/
servers:
  - url: https://www.datafirst.uct.ac.za/dataportal/index.php/api
    description: DataFirst NADA public catalog API
tags:
  - name: catalog
    description: Browse and search the microdata catalog.
paths:
  /catalog:
    get:
      tags: [catalog]
      summary: List catalog studies
      description: >-
        Returns a paginated list of catalog entries (surveys / studies) with
        summary metadata. Confirmed on 2026-08-30 returning 582 surveys.
      operationId: listCatalog
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of catalog studies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
  /catalog/search:
    get:
      tags: [catalog]
      summary: Search catalog studies
      description: >-
        Search the catalog of studies by free-text keyword. Confirmed to return
        the same structured catalog response as the catalog listing endpoint,
        with the applied filters echoed back.
      operationId: searchCatalog
      parameters:
        - name: sk
          in: query
          description: Search keywords / free-text query.
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of matching catalog studies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
  /catalog/{idno}:
    get:
      tags: [catalog]
      summary: Get one study by persistent identifier
      description: >-
        Returns the full record for a single study, addressed by its persistent
        IDNO (not its numeric id — a numeric id returns 400 IDNO-NOT-FOUND).
        The response carries a `dataset` object plus a nested `metadata` block
        holding the study's DDI-style documentation.
      operationId: getStudy
      parameters:
        - $ref: '#/components/parameters/idno'
      responses:
        '200':
          description: The study record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyResponse'
        '400':
          description: Unknown or malformed IDNO.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /catalog/data_files/{idno}:
    get:
      tags: [catalog]
      summary: List the data files of a study
      description: >-
        Returns the study's data files keyed by file id (F1, F3, F4 …), each
        with case and variable counts.
      operationId: listStudyDataFiles
      parameters:
        - $ref: '#/components/parameters/idno'
      responses:
        '200':
          description: The study's data files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataFilesResponse'
        '400':
          description: Unknown or malformed IDNO.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /catalog/variables/{idno}:
    get:
      tags: [catalog]
      summary: List the variables of a study
      description: >-
        Returns the study's variables with their file id, variable id, name and
        label, plus a total count.
      operationId: listStudyVariables
      parameters:
        - $ref: '#/components/parameters/idno'
      responses:
        '200':
          description: The study's variables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariablesResponse'
        '400':
          description: Unknown or malformed IDNO.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of rows per page.
      schema:
        type: integer
        minimum: 1
        default: 15
    offset:
      name: offset
      in: query
      description: Number of rows to skip.
      schema:
        type: integer
        minimum: 0
        default: 0
    idno:
      name: idno
      in: path
      required: true
      description: Persistent study identifier (IDNO).
      schema:
        type: string
      example: mwi-alpha-him-karonga-2002-2017-v1
  schemas:
    Error:
      type: object
      description: >-
        Error envelope observed on 2026-08-30. Note that the service returns
        HTTP 400 for a not-found study, not 404.
      properties:
        status:
          type: string
          example: failed
        message:
          type: string
          example: IDNO-NOT-FOUND
    CatalogResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/CatalogResult'
    CatalogResult:
      type: object
      properties:
        found:
          type: integer
          description: Number of matching studies.
          example: 582
        total:
          type: integer
          description: Total number of studies in the catalog.
          example: 582
        limit:
          type: integer
          example: 15
        offset:
          type: integer
          example: 0
        search_counts_by_type:
          type: object
          description: Counts of results grouped by study type.
          additionalProperties:
            type: integer
          example:
            survey: 582
            timeseries: 0
        rows:
          type: array
          items:
            $ref: '#/components/schemas/Study'
    StudyResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        dataset:
          $ref: '#/components/schemas/StudyDetail'
    StudyDetail:
      type: object
      description: Full record for one study.
      properties:
        id:
          type: integer
          example: 890
        doi:
          type: string
          nullable: true
          example: https://doi.org/10.25828/wcty-q497
        repositoryid:
          type: string
          description: Owning collection / repository code.
          example: ALPHA
        type:
          type: string
          example: survey
        idno:
          type: string
          example: mwi-alpha-him-karonga-2002-2017-v1
        title:
          type: string
          example: ALPHA HIV Incidence and Mortality Data
        year_start:
          type: integer
          example: 2002
        year_end:
          type: integer
          example: 2017
        nation:
          type: string
          example: Malawi
        authoring_entity:
          type: string
        published:
          type: integer
          example: 1
        created:
          type: string
          example: '2022-01-19T12:59:56+00:00'
        changed:
          type: string
          example: '2024-08-23T09:59:07+00:00'
        varcount:
          type: integer
          example: 25
        total_views:
          type: integer
        total_downloads:
          type: integer
        formid:
          type: integer
        data_access_type:
          type: string
          example: licensed
        remote_data_url:
          type: string
          nullable: true
        data_class_id:
          type: integer
          nullable: true
        data_class_code:
          type: string
          nullable: true
        data_class_title:
          type: string
          nullable: true
        thumbnail:
          type: string
        metadata:
          type: object
          description: >-
            Nested DDI-style study documentation (study description, producers,
            coverage, access conditions). Shape varies by study.
          additionalProperties: true
    DataFilesResponse:
      type: object
      properties:
        datafiles:
          type: object
          description: Data files keyed by file id (F1, F3, F4 …).
          additionalProperties:
            $ref: '#/components/schemas/DataFile'
    DataFile:
      type: object
      properties:
        id:
          type: integer
          example: 7911
        sid:
          type: integer
          description: Internal study id.
          example: 890
        file_id:
          type: string
          example: F3
        file_name:
          type: string
          example: incidence_Karonga
        description:
          type: string
          nullable: true
        case_count:
          type: integer
          example: 25136
        var_count:
          type: integer
          example: 12
        producer:
          type: string
          nullable: true
        data_checks:
          type: string
          nullable: true
        missing_data:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
    VariablesResponse:
      type: object
      properties:
        total:
          type: integer
          example: 25
        variables:
          type: array
          items:
            $ref: '#/components/schemas/Variable'
    Variable:
      type: object
      properties:
        uid:
          type: integer
          example: 1736429
        sid:
          type: integer
          example: 890
        fid:
          type: string
          description: File id the variable belongs to.
          example: F3
        vid:
          type: string
          description: Variable id within the file.
          example: V21
        name:
          type: string
          example: sex
        labl:
          type: string
          description: Variable label.
          example: Sex
    Study:
      type: object
      description: A single catalog study (survey) as returned in a listing.
      properties:
        id:
          type: integer
          example: 890
        type:
          type: string
          example: survey
        idno:
          type: string
          example: mwi-alpha-him-karonga-2002-2017-v1
        doi:
          type: string
          nullable: true
          example: https://doi.org/10.25828/wcty-q497
        title:
          type: string
          example: ALPHA HIV Incidence and Mortality Data
        subtitle:
          type: string
          example: Karonga 2002-2017
        nation:
          type: string
          example: Malawi
        authoring_entity:
          type: string
        form_model:
          type: string
          example: licensed
        data_class_id:
          type: integer
          nullable: true
        year_start:
          type: integer
          example: 2002
        year_end:
          type: integer
          example: 2017
        repositoryid:
          type: string
          example: ALPHA
        repo_title:
          type: string
          example: ALPHA Network
        created:
          type: string
        changed:
          type: string
        total_views:
          type: integer
        total_downloads:
          type: integer
        varcount:
          type: integer
        thumbnail:
          type: string
        url:
          type: string
          description: Public HTML landing page for the study.