Interact with data sources
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