Operations relating to managing ephemeris and data products data
openapi: 3.0.1
info:
title: AuroraX Application.wadl Manage Data 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: Manage Data
description: Operations relating to managing ephemeris and data products data
paths:
/api/v1/data_sources/{identifier}/data_products:
post:
tags:
- Manage Data
summary: Add a data product
description: 'Adds one or more Data Product records to the set of Data Products for this Data Source record. Must be an Administrator, Owner of this Data Source or have been assigned Maintainer of this Data Source.
This end-point will accept very large files or continuous streams containing data product records. Data is processed asynchronously.'
operationId: addDataProducts
parameters:
- name: identifier
in: path
description: The identifier specified in the Data Source record
required: true
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LoadDataProductSpecification'
required: true
responses:
'202':
description: The data product stream was accepted for processing.
'400':
description: 'Errors generated during load.
Please refer to the documentation for correctness of this operation. Because this operation is asynchronous, some errors occurring later in the load may not be present in this response'
content:
application/json:
schema:
type: array
items:
$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"
'403':
description: 'Not Permitted
Only the Data Source Owner, a Maintainer, or an Administrator may post new data products.'
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:
- Manage Data
summary: Deletes a Data Product record
description: "*Must be the Data Source Maintainer, Owner, or have Administrator access in order to perform this operation* \n\n*Must be authenticated*"
operationId: deleteDataProduct
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
requestBody:
description: The delete operation specification
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDataProductSpecification'
required: true
responses:
'200':
description: Data Product 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, a Maintainer, or an Administrator may delete data products.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: identifier not found
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}/ephemeris:
post:
tags:
- Manage Data
summary: Add ephemeris data
description: 'Adds data to the set of Ephemeris for this Data Source record. Must be an Administrator, Owner of this Data Source or have been assigned Maintainer of this Data Source.
This end-point will accept very large files or continuous streams containing Ephemeris data. Data is processed asynchronously.'
operationId: addEphemerisData
parameters:
- name: identifier
in: path
description: The identifier specified in the Data Source record
required: true
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LoadEphemerisSpecification'
required: true
responses:
'202':
description: The ephemeris stream was accepted for processing.
'400':
description: 'Errors generated during load.
Please refer to the documentation for correctness of this operation. Because this operation is asynchronous, some errors occurring later in the load may not be present in this response'
content:
application/json:
schema:
type: array
items:
$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, a Maintainer, or an Administrator may post new ephemeris data.'
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:
- Manage Data
summary: Delete a range of Ephemeris records. This interface is asynchronous.
description: "*Must be the Data Source Maintainer, Owner, or have Administrator access in order to perform this operation* \n\n*Must be authenticated*"
operationId: deleteEphemeris
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
requestBody:
description: The specification that matches the identifier (for data integrity)
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEphemerisSpecification'
required: true
responses:
'202':
description: Delete request accepted
'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, a Maintainer, or an Administrator may delete ephemeris data.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: identifier not found
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}/ephemeris/delete_jobs/{delete_job_id}:
get:
tags:
- Manage Data
summary: Get a recent (within 1 hour) delete job details
operationId: getEphemerisDeleteJobDetail
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
- name: delete_job_id
in: path
description: The delete job identifier
required: true
schema:
type: string
responses:
'200':
description: Delete job details
content:
application/json:
schema:
type: array
items:
type: string
'404':
description: identifier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/data_sources/{identifier}/ephemeris/delete_jobs:
get:
tags:
- Manage Data
summary: List recent (within 1 hour) delete jobs
operationId: listEphemerisDeleteJobs
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
responses:
'200':
description: List of recent delete jobs
content:
application/json:
schema:
type: array
items:
type: string
'404':
description: identifier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
components:
schemas:
DeleteDataProductSpecification:
required:
- instrument_type
- platform
- program
type: object
properties:
program:
type: string
platform:
type: string
instrument_type:
type: string
urls:
type: array
items:
type: string
LoadEphemerisSpecification:
required:
- epoch
- instrument_type
- platform
- program
type: object
properties:
program:
type: string
platform:
type: string
instrument_type:
type: string
epoch:
type: string
format: date-time
location_geo:
$ref: '#/components/schemas/Location'
location_gsm:
$ref: '#/components/schemas/Location'
nbtrace:
$ref: '#/components/schemas/Location'
sbtrace:
$ref: '#/components/schemas/Location'
metadata:
$ref: '#/components/schemas/JsonNode'
JsonNode:
type: object
LoadDataProductSpecification:
required:
- data_product_type
- end
- instrument_type
- platform
- program
- start
- url
type: object
properties:
program:
type: string
platform:
type: string
instrument_type:
type: string
start:
type: string
format: date-time
end:
type: string
format: date-time
url:
type: string
metadata:
$ref: '#/components/schemas/JsonNode'
data_product_type:
type: string
enum:
- keogram
- montage
- movie
- summary_plot
- data_availability
DeleteEphemerisSpecification:
required:
- end
- instrument_type
- platform
- program
- start
type: object
properties:
program:
type: string
platform:
type: string
instrument_type:
type: string
start:
type: string
format: date-time
end:
type: string
format: date-time
Location:
type: object
properties:
lat:
maximum: 90
minimum: -90
type: number
lon:
maximum: 180
minimum: -180
type: number
description: A list of latitude and longitude locations of your choice
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