University of Calgary AuroraX Data Sources API

openapi: 3.2.0
info:
  title: AuroraX Data Sources API
  description: '## Overview


    This webpage is an interactive documentation interface for the AuroraX RESTful API.'
  version: stable
servers:
- url: https://api.aurorax.space
  description: AuroraX production server
  variables: {}
- url: https://api.staging.aurorax.space
  description: AuroraX staging server
  variables: {}
- url: http://localhost:8080/
  description: Local Development and Debugging
  variables: {}
tags:
- name: Data Sources
  description: Interact with data sources
paths:
  /api/v1/data_sources:
    get:
      tags:
      - Data Sources
      summary: List all data sources
      description: Data Sources are entities like satellites and ground stations (platforms) that produce data.
      operationId: getList
      parameters:
      - name: program
        in: query
        description: Filter by Program
        schema:
          type: string
      - name: platform
        in: query
        description: Filter by Platform
        schema:
          type: string
      - name: instrument_type
        in: query
        description: Filter by Instrument Type
        schema:
          type: string
      - name: source_type
        in: query
        description: Filter by Source Type
        schema:
          type: string
          enum:
          - ground
          - heo
          - leo
          - lunar
          - event_list
          - not_applicable
      - name: owner
        in: query
        description: Filter by Owner
        schema:
          type: string
      - name: format
        in: query
        description: The format of the Data Source returned. Default is basic_info.
        schema:
          type: string
          enum:
          - identifier_only
          - basic_info
          - with_metadata
          - full_record
      - name: include_stats
        in: query
        description: Include the data_source stats with the response. Default is false.
        schema:
          type: boolean
      responses:
        '200':
          description: List of data sources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Data_Source'
    post:
      tags:
      - Data Sources
      summary: Add an Data Source record
      description: '*Must have the Administrator or Owner role to perform this operation*


        *Must be authenticated*'
      operationId: add_1
      requestBody:
        description: The Data Source record to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Data_Source'
        required: true
      responses:
        '200':
          description: Data Source record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Data_Source'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '401':
          description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid API key\n * Invalid access token\n * Access token expired"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '403':
          description: 'Not Permitted

            Only the Data Source Owner or an Administrator may create new data sources.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '409':
          description: "Duplicate. \nThere is already a Data Source record with this identifier"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '503':
          description: 'Maintenance Mode


            The API is in maintenance mode. This endpoint is currently offline.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
      - ApiKeyAuth: []
      - AccessToken: []
  /api/v1/data_sources/{identifier}:
    get:
      tags:
      - Data Sources
      summary: Get details about a Data Source
      operationId: getDetail
      parameters:
      - name: identifier
        in: path
        description: The identifier of the Data Source
        required: true
        schema:
          type: integer
          format: int32
      - name: format
        in: query
        description: The format of the Data Source returned. Default is basic_info.
        schema:
          type: string
          enum:
          - identifier_only
          - basic_info
          - with_metadata
          - full_record
      - name: include_stats
        in: query
        description: Include the data_source stats with the response. Default is false.
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Data_Source'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
        '404':
          description: identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
    put:
      tags:
      - Data Sources
      summary: Update an Data Source record
      description: '*Must be an Administrator or be the Owner of this record*


        *Must be authenticated*'
      operationId: update_1
      parameters:
      - name: identifier
        in: path
        description: The identifier of the Data Source
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: The Data Source record to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Data_Source'
        required: true
      responses:
        '200':
          description: Data Source record updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Data_Source'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '401':
          description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid API key\n * Invalid access token\n * Access token expired"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '403':
          description: 'Not Permitted

            Only the Data Source Owner or an Administrator may update data sources.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '404':
          description: identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '409':
          description: "Duplicate. \nThere is already an Data Source record for this identifier"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '503':
          description: 'Maintenance Mode


            The API is in maintenance mode. This endpoint is currently offline.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
      - ApiKeyAuth: []
      - AccessToken: []
    delete:
      tags:
      - Data Sources
      summary: Delete an Data Source record
      description: '*Must be an Owner of the Data Source or an Administrator in order to perform this operation*


        *Must be authenticated*'
      operationId: delete_1
      parameters:
      - name: identifier
        in: path
        description: The identifier of the Data Source
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Data Source record deleted
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '401':
          description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid API key\n * Invalid access token\n * Access token expired"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '403':
          description: 'Not Permitted

            Only the Data Source Owner or an Administrator may delete data sources.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '404':
          description: identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '409':
          description: "Conflict. \nThere is existing data associated with this source. Remove the data first, and then try this operation again."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '503':
          description: 'Maintenance Mode


            The API is in maintenance mode. This endpoint is currently offline.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
      - ApiKeyAuth: []
      - AccessToken: []
    patch:
      tags:
      - Data Sources
      summary: Partially update an Data Source record. Omitted fields are ignored
      description: '*Must be an Administrator or be the Owner of this record*


        *Must be authenticated*'
      operationId: partialUpdate_1
      parameters:
      - name: identifier
        in: path
        description: The identifier of the Data Source
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: The Data Source record to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Data_Source'
        required: true
      responses:
        '200':
          description: Data Source record updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Data_Source'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '401':
          description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid API key\n * Invalid access token\n * Access token expired"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '403':
          description: 'Not Permitted

            Only the Data Source Owner or an Administrator may update data sources.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '404':
          description: identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '409':
          description: "Duplicate. \nThere is already an Data Source record for this identifier"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '503':
          description: 'Maintenance Mode


            The API is in maintenance mode. This endpoint is currently offline.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
      - ApiKeyAuth: []
      - AccessToken: []
  /api/v1/data_sources/{identifier}/stats:
    get:
      tags:
      - Data Sources
      summary: Get some statistics about a Data Source, like the earliest/latest ephemeris…
      operationId: getStats
      parameters:
      - name: identifier
        in: path
        description: The identifier of the Data Source
        required: true
        schema:
          type: integer
          format: int32
      - name: format
        in: query
        description: The format of the Data Source returned. Default is basic_info.
        schema:
          type: string
          enum:
          - identifier_only
          - basic_info
          - with_metadata
          - full_record
      - name: slow
        in: query
        description: Query the data directly (slower) for more accurate results. Default is false.
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceStats'
        '404':
          description: identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      deprecated: true
  /api/v1/data_sources/search:
    post:
      tags:
      - Data Sources
      summary: Search for data sources
      description: Find the data sources matching a set of search parameters. This endpoint is synchronous.
      operationId: search_1
      parameters:
      - name: format
        in: query
        description: The format of the Data Source returned. Default is basic_info.
        schema:
          type: string
          enum:
          - identifier_only
          - basic_info
          - with_metadata
          - full_record
      - name: include_stats
        in: query
        description: Include the data_source stats with the response
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSourceQuery'
        required: true
      responses:
        '200':
          description: List of data sources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Data_Source'
        '400':
          description: 'Missing or invalid parameters.


            Please refer to the documentation for correctness of this operation.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
components:
  schemas:
    DataSourceStats:
      type: object
      properties:
        data_source:
          $ref: '#/components/schemas/Data_Source'
        earliest_ephemeris_loaded:
          type: string
          format: date-time
        latest_ephemeris_loaded:
          type: string
          format: date-time
        ephemeris_count:
          type: integer
          format: int32
        earliest_data_product_loaded:
          type: string
          format: date-time
        latest_data_product_loaded:
          type: string
          format: date-time
        data_product_count:
          type: integer
          format: int32
      description: Some basic stats about this data_source, like number of ephemeris records. Read only.
    DataSourceQuery:
      type: object
      properties:
        programs:
          type: array
          items:
            type: string
        platforms:
          type: array
          items:
            type: string
        instrument_types:
          type: array
          items:
            type: string
    MetadataSchema:
      type: object
      properties:
        field_name:
          type: string
          description: The name of the field found in the ephemeris metadata
        description:
          type: string
          description: A brief description of what the metadata field represents
        data_type:
          type: string
          description: An indicator to let you know what filter operations are available. Strings allow for =, !=, and in. Decimals allow for =, !=, <, >, <=, >=, and in.
        allowed_values:
          type: array
          description: An optional list of possible values available in the metadata.
          items:
            type: string
            description: An optional list of possible values available in the metadata.
        additional_description:
          type: string
          description: More details about what this metadata field is about
        searchable:
          type: boolean
          description: Used by UI's to include it in metadata fields exposed as searchable through the conjunction interface. The API allows for all fields to be searchable but some applications may chose to hide any fields marked searchable=false
      description: Describes the metadata fields found on Ephemeris data.
    JsonNode:
      type: object
    ErrorDocument:
      type: object
      properties:
        error_message:
          type: string
          description: If an error code exists, this will have contextual information for debugging
        error_code:
          type: string
          description: The error code
          enum:
          - Nil
          - Ok
          - NotPermitted
          - NotAuthorized
          - Duplicate
          - AssertionError
          - NotFound
          - ApplicationError
          - NotImplemented
          - ToManyRequests
          - Other
          - Conflict
          - NotAuthenticated
          - Unavailable
      description: This model provides additional details about error conditions that can be used for debugging.
    Data_Source:
      required:
      - display_name
      - instrument_type
      - platform
      - program
      - source_type
      type: object
      properties:
        identifier:
          type: integer
          description: Uniquely identifies this record. Optional when adding a new source record; system generated, unless this is a replacement (e.g., delete old, create new with same identifier as old).
          format: int32
        program:
          type: string
          description: 'Examples: themis, themis-asi, rbsp'
        platform:
          type: string
          description: 'Examples: themisa, gill, rbspb'
        instrument_type:
          type: string
          description: 'Examples: pancromatic-asi'
        source_type:
          type: string
          description: g = Ground, h = Highly Eliptical Orbit, l = Low Earth Orbit
          enum:
          - ground
          - heo
          - leo
          - lunar
          - event_list
          - not_applicable
        display_name:
          type: string
          description: A friendly display name for web applications
        ephemeris_metadata_schema:
          type: array
          description: The ephemeris metadata schema and descriptions
          items:
            $ref: '#/components/schemas/MetadataSchema'
        data_product_metadata_schema:
          type: array
          description: The data_product metadata schema and descriptions
          items:
            $ref: '#/components/schemas/MetadataSchema'
        owner:
          type: string
          description: The Owner of this Data Source record. Defaults to the currently logged in user.
        maintainers:
          type: array
          description: The list of Maintainers
          items:
            type: string
            description: The list of Maintainers
        stats:
          $ref: '#/components/schemas/DataSourceStats'
        metadata:
          $ref: '#/components/schemas/JsonNode'
      description: Things that produce data, like satellites, ground stations/instruments, platforms
  securitySchemes:
    AccessToken:
      type: http
      description: Send the Authorization header found in the response of a successful /authentication request on all  secure endpoints. Copy it verbatim to the request header. It is fine to send this header on all requests  to the API. The value in Swagger UI should only include the access token part (leave out 'Bearer').
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: Generated by server
    ApiKeyAuth:
      type: apiKey
      description: API keys are intended to be used by non-interactive software interfacing with the REST API. These can  be used instead of an Access Token approach.
      name: x-aurorax-api-key
      in: header