openapi: 3.0.1
info:
  title: Ontoserver Management APIs
  description: Various non-FHIR APIs for managing the operation of an Ontoserver instance
    including its Syndication feed.
  contact:
    url: https://ontoserver.csiro.au/
    email: ontoserver-support@csiro.au
servers:
- url: https://r4.ontoserver.csiro.au
  description: CSIRO R4 Terminology Server Sandbox
- url: https://tx.ontoserver.csiro.au
  description: CSIRO Production Server
- url: http://localhost:8080
  description: Local server
tags:
- name: Admin
- name: Syndication
paths:
  /synd/setSyndicationStatus:
    post:
      tags:
      - Syndication
      description: Change the downstream syndication status for a Resource on the
        server
      operationId: setSyndicationStatus
      parameters:
      - name: resourceType
        in: query
        description: "The type of the resource, e.g. ValueSet, CodeSystem, NamingSystem"
        required: true
        schema:
          type: string
      - name: id
        in: query
        description: The id of the resource
        required: true
        schema:
          type: string
      - name: syndicate
        in: query
        description: Whether to publish the resource in the downstream syndication
          feed
        required: true
        schema:
          type: boolean
      responses:
        "200":
          description: OK
  /synd/setIndexSyndicationStatus:
    post:
      tags:
      - Syndication
      description: Change the downstream syndication status for a SNOMED/LOINC code
        system on the server
      operationId: setIndexSyndicationStatus
      parameters:
      - name: codeSystemId
        in: query
        description: "A code system identifier, e.g. http://snomed.info/sct"
        required: true
        schema:
          type: string
      - name: codeSystemVersion
        in: query
        description: The version of the specified code system
        required: true
        schema:
          type: string
      - name: syndicate
        in: query
        description: Whether to publish a binary index for the code system
        required: true
        schema:
          type: boolean
      responses:
        "200":
          description: OK
  /synd/redoPreload:
    post:
      tags:
      - Syndication
      description: "Re-executes the data load performed at start in the preload feed\
        \ without having to restart the server.<p>A successful result will provide\
        \ a Location header referencing the preload job, and return the job's current\
        \ status.<p>Execution will be asynchronous or synchronous depending upon the\
        \ configuration of atom.preload.async, which is true by default."
      operationId: redoPreload
      responses:
        "200":
          description: Preload execution has been started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
              example:
                id: preload-20221018T145537+1000
                name: Preload content from classpath:preload.xml
                status: running
        "500":
          description: Preload could not be re-executed
          content:
            application/fhir+json: {}
  /synd/fetchSyndicatedContentEntry:
    post:
      tags:
      - Syndication
      description: "Fetch an artifact from the upstream syndication feed into the\
        \ server. For entries of type Bundle: only 'batch' and 'collection' are supported.\
        \ Future versions may support 'transaction', and unsupported contained Resource\
        \ types will be ignored."
      operationId: fetchSyndicatedContentEntry
      parameters:
      - name: entryId
        in: query
        description: The atom entry ID to fetch
        required: false
        schema:
          type: string
      - name: resourceType
        in: query
        description: The type of resource to fetch
        required: false
        schema:
          type: string
      - name: url
        in: query
        description: "The URL of the resource (CodeSystem, ValueSet, ConceptMap or\
          \ StructureDefinition) to fetch"
        required: false
        schema:
          type: string
      - name: version
        in: query
        description: The version of the resource to fetch
        required: false
        schema:
          type: string
      - name: bundleInterpretation
        in: query
        description: "If the entry is a Bundle, how to process the Bundle. Valid values\
          \ are: 'batch' and 'collection'"
        required: false
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/fhir+json: {}
  /api/vacuum:
    post:
      tags:
      - Admin
      description: "Checks for, and optionally cleans up, extraneous indexing content\
        \ in the filesystem."
      operationId: vacuum
      parameters:
      - name: cleanup
        in: query
        description: "If 'true', then actually delete the extraneous content"
        required: false
        schema:
          type: boolean
          default: false
      - name: verbose
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "500":
          description: Failure
          content:
            '*/*':
              schema:
                type: object
                additionalProperties:
                  type: object
        "200":
          description: Success
          content:
            '*/*':
              schema:
                type: object
                additionalProperties:
                  type: object
  /api/indexCodeSystem:
    post:
      tags:
      - Admin
      description: "Index a SNOMED/LOINC code system, using a syndication server if\
        \ available"
      operationId: indexCodeSystem
      parameters:
      - name: codeSystemId
        in: query
        description: "A code system identifier, e.g. http://snomed.info/sct"
        required: true
        schema:
          type: string
      - name: codeSystemVersion
        in: query
        description: "The version (or optionally, for SNOMED, the Edition) of the\
          \ specified code system"
        required: false
        schema:
          type: string
      - name: validate
        in: query
        description: Indicates whether the server should validate the index if it
          already exists
        required: true
        schema:
          type: boolean
      - name: buildLocal
        in: query
        description: "Do not use BINARY indexes from syndication feed, but build them\
          \ locally"
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: string
  /api/deleteCodeSystem:
    post:
      tags:
      - Admin
      description: Remove a SNOMED/LOINC code system
      operationId: deleteCodeSystem
      parameters:
      - name: codeSystemId
        in: query
        description: "A code system identifier, e.g. http://snomed.info/sct"
        required: true
        schema:
          type: string
      - name: codeSystemVersion
        in: query
        description: The version of the specified code system
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
  /api/addBundle:
    post:
      tags:
      - Admin
      description: Add a bundle of FHIR Resources to the server
      operationId: addBundleFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              type: object
              properties:
                file:
                  type: string
                  description: A FHIR Bundle object containing a set of resources
                  format: binary
          application/fhir+json: {}
          application/fhir+xml: {}
          application/json: {}
          application/xml: {}
          application/json+fhir: {}
          application/xml+fhir: {}
      responses:
        "200":
          description: OK
          content:
            application/json: {}
  /synd/syndication.xml:
    get:
      tags:
      - Syndication
      description: Retrieve the server's downstream syndication feed (if available)
      operationId: getSyndicationFeed
      parameters:
      - name: canonical
        in: query
        description: Filter feed to match these content identifiers; uses FHIR canonical
          syntax
        required: false
        schema:
          type: array
          items:
            type: string
      - name: category
        in: query
        description: Filter feed to match these categories
        required: false
        schema:
          type: array
          items:
            type: string
      - name: fhirVersion
        in: query
        description: Filter feed to match these FHIR versions
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/atom+xml:
              schema:
                type: string
  /synd/getSyndicationStatus:
    get:
      tags:
      - Syndication
      description: Get the downstream syndication status for a Resource on the server
      operationId: getSyndicationStatus
      parameters:
      - name: resourceType
        in: query
        description: "The type of the resource, e.g. ValueSet, CodeSystem, NamingSystem"
        required: true
        schema:
          type: string
      - name: id
        in: query
        description: The id of the resource
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: string
  /synd/getBinaryIndexZip:
    get:
      tags:
      - Syndication
      description: Retrieve the binary index for a code system from the server (if
        available)
      operationId: getBinaryIndexZip
      parameters:
      - name: codeSystemId
        in: query
        description: "A code system identifier, e.g. http://snomed.info/sct"
        required: true
        schema:
          type: string
      - name: codeSystemVersion
        in: query
        description: The version of the specified code system
        required: true
        schema:
          type: string
      - name: indexVersion
        in: query
        description: The internal version of the binary index format
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/version:
    get:
      tags:
      - Admin
      description: Retrieve the version of Ontoserver and HAPI
      operationId: version
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
  /api/upstream.xml:
    get:
      tags:
      - Admin
      description: Retrieve merged form of the server's upstream syndication feeds
        (if available)
      operationId: getUpstreamFeed
      responses:
        "200":
          description: OK
          content:
            application/atom+xml:
              schema:
                type: string
  /api/startupProbe:
    get:
      tags:
      - Admin
      description: Returns startup status information.
      operationId: startupProbe
      parameters:
      - name: status
        in: query
        description: "Status property to check. One of: Live, Ready"
        required: true
        schema:
          type: string
          enum:
          - Live
          - Ready
      responses:
        "503":
          description: Probed state is false
          content:
            text/plain:
              schema:
                type: string
        "200":
          description: Probed state is true
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Unknown state requested
          content:
            text/plain:
              schema:
                type: string
  /api/mode:
    get:
      tags:
      - Admin
      description: Retrieve the security modes of Ontoserver
      operationId: mode
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
      security:
      - oauth2:
        - onto/api.read
  /api/jobs:
    get:
      tags:
      - Admin
      description: Retrieve a list of the background Jobs the server has run/is running
        along with their status
      operationId: getJobs
      parameters:
      - name: jobId
        in: query
        description: A job identifier
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
      security:
      - oauth2:
        - onto/api.read
  /api/indexedCodeSystems:
    get:
      tags:
      - Admin
      description: Get a list of the code systems that are indexed on this server
      operationId: getIndexedCodeSystems
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CodeSystemDetails"
  /api/codeSystems:
    get:
      tags:
      - Admin
      description: Get a list of the code system sources that are loaded in this server
      operationId: getCodeSystemsInfo
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CodeSystemInfo"
  /api/availableCodeSystemSources:
    get:
      tags:
      - Admin
      description: Get a list of the code system sources that are available to this
        server
      operationId: getAvailableCodeSystemSources
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AtomArtifact"
  /api/availableCodeSystemIndexes:
    get:
      tags:
      - Admin
      description: Get a list of the code system indexes that are available to this
        server
      operationId: getAvailableCodeSystemIndexes
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AtomArtifact"
  /api/auditReports:
    get:
      tags:
      - Admin
      description: Get all current audit reports
      operationId: getAuditReports
      responses:
        "200":
          description: OK
          content:
            application/fhir+json:
              schema:
                type: string
            application/json:
              schema:
                type: string
components:
  schemas:
    Status:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          writeOnly: true
        success:
          type: boolean
        failing:
          type: boolean
        finished:
          type: boolean
    CodeSystemDetails:
      type: object
      properties:
        id:
          type: string
        version:
          type: string
        url:
          type: string
        title:
          type: string
        isSupplement:
          type: boolean
        sha256:
          type: string
        lastUpdated:
          type: string
        metaVersion:
          type: string
        indexStatus:
          type: string
          enum:
          - OK
          - MISSING
          - CORRUPT
          - VERSION_MISMATCH
          - NOT_INDEXED
          - VERSION_UPGRADABLE
    CodeSystemInfo:
      type: object
      properties:
        codeSystem:
          $ref: "#/components/schemas/CodeSystemReference"
        name:
          type: string
        sourceAvailable:
          type: boolean
        binaryAvailable:
          type: boolean
        inDatabase:
          type: boolean
        status:
          type: string
          enum:
          - OK
          - MISSING
          - CORRUPT
          - VERSION_MISMATCH
          - NOT_INDEXED
          - VERSION_UPGRADABLE
        syndicated:
          type: boolean
    CodeSystemReference:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        version:
          type: string
        caseSensitive:
          type: boolean
        metaVersion:
          type: string
    AtomArtifact:
      type: object
      properties:
        type:
          type: string
          enum:
          - LOINC
          - RF2_SOURCE_DELTA
          - RF2_SOURCE_SNAPSHOT
          - RF2_SOURCE_FULL
          - RF2_SOURCE_ALL
          - BINARY
          - FHIR_BUNDLE
          - FHIR_CODESYSTEM
          - FHIR_CONCEPTMAP
          - FHIR_VALUESET
          - FHIR_STRUCTUREDEFINITION
          - FHIR_NAMINGSYSTEM
          - FHIR_PACKAGE
          - BINARY_RETRACT
          - LOINC_RETRACT
          - FHIR_CODESYSTEM_RETRACT
          - FHIR_CONCEPTMAP_RETRACT
          - FHIR_VALUESET_RETRACT
          - FHIR_STRUCTUREDEFINITION_RETRACT
        signatures:
          type: object
          additionalProperties:
            type: string
        codeSystem:
          $ref: "#/components/schemas/CodeSystemReference"
        baseModule:
          type: string
        baseEffectiveTime:
          type: string
        indexVersion:
          type: string
        security:
          type: array
          items:
            type: string
        id:
          type: string
        bundleType:
          type: string
          enum:
          - DOCUMENT
          - MESSAGE
          - TRANSACTION
          - TRANSACTIONRESPONSE
          - BATCH
          - BATCHRESPONSE
          - HISTORY
          - SEARCHSET
          - COLLECTION
          - "NULL"
        contentItemIdentifier:
          type: string
        contentItemVersion:
          type: string
        dependencies:
          type: array
          items:
            $ref: "#/components/schemas/AtomArtifact"
        validated:
          type: boolean