openapi: 3.0.1
info:
  title: AuroraX Application.wadl Data Sources API
  description: "## Overview\n\nThis webpage is an interactive documentation interface for the AuroraX RESTful API. This API\nis used by several applications including the AuroraX Conjunction Search, Event Explorer,\nKeogramist, PyAuroraX, and IDL-AuroraX. You can view these applications and libraries at\n<a href='https://aurorax.space' target='_blank'>https://aurorax.space</a> and\n<a href='https://github.com/aurorax-space' target='_blank'>https://github.com/aurorax-space</a>.\n\nDetailed documentation about the AuroraX platform and examples of using this API can be found at\n<a href='https://docs.aurorax.space' target='_blank'>https://docs.aurorax.space</a>.\n\nBelow, we outline the major categories of endpoints available for use:\n\n| Interface        | Description                                                                 |\n| ---------------- | --------------------------------------------------------------------------- |\n| Accounts         | Operations relating to user accounts, API keys, and saved user data         |\n| Authentication   | Authentication using an email address and password, or an API key           |\n| Availability     | Retrieve information describing what data is in the database                |\n| Data Sources     | Interact with data sources                                                  |\n| Conjunctions     | Search for conjunctions between multiple sets of data sources               |\n| Ephemeris        | Search and manage ephemeris data associated with a data source              |\n| Data Products    | Search and manage data products data associated with a data source          |\n| Utils            | Utilities, such as describing a search query in an SQL-like format          |\n\n## Authentication\n\nAuroraX allows for two methods of authentication:\n\n1. Authenticate via username and password using the /authenticate endpoint to obtain an access\n   token. Access tokens need to be sent on every request for secure resources. Inactive access tokens\n   timeout after 30 minutes.\n\n2. Authenticate using an API key sent in the request header (key called 'x-aurorax-api-key')\n\nMore information can be found\n<a href='https://docs.aurorax.space/code/advanced_usage/authentication' target='_blank'>here</a>.\n\n## Errors\n\nThis API uses standard HTTP status codes to indicate the success or failure of the\nAPI call. When an error occurs, the body of the response will be JSON and contain an error code\nand message. All errors will respond with this format:\n```\n{\n    \"error_code\": \"DUPLICATE\",\n    \"error_message\": \"There was a duplicate record found. No changes were made.\"\n}\n```\n"
  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* \n\n*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* \n\n*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* \n\n*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* \n\n*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 loaded into AuroraX  and number of ephemeris records loaded. This will be removed and combined with list data_source  and get data_source detail.
      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:
    JsonNode:
      type: object
    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.
    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
    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
    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.
  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