This document contains various proposals how the FLARECAST REST API could look like The idea is that all algorithms communicate through REST URLs with the databases.
URLs are used to create, read, update and delete records (CRUD). As data exchange format we propose to use JSON. JSON can be natively read by many programming languages, such as Python, IDL, Java, JavaScript, ...
This document does not contain a normative definition of the API, but rather examples that can be used for further discussions.
As illustrated in the Architecture overview the FLARECAST infrastructure consists of several databases. All of these databases store different types of resources.
| Database | Resource |
|---|---|
| Data Archive | Observation (e.g. FITS-Files) |
| Staging Table | Event, ... (e.g. Event lists) |
| Feature Property Database | Feature (such as Active Regions), FeatureProperty (e.g. Area, Contour, Zurich-Class, ...) |
| Predictions Config DB | Scalars, Vectors, Matrices (e.g. Algo-Configurations) |
| Prediction DB | ? |
| Infrastructure Configuration DB | Algorithm, Person, |
Resources
Anything accessible through the API is a "resource". All available resources can be listed.
| Get list of observation types | |
|---|---|
| Query | https://api.flarecast.eu/resources/list |
| Result | {
{
"people" : {
"description": "Persons or groups responsible",
"baseURL": "
},
"algorithms" : {
"description" : "Registered algorithms (read-only)",
"baseURL" : "https://api.flarecast.eu/algorithms/
},
"features" : {
"description" : "Features accessible through this API",
"baseURL" : "https://api.flarecast.eu/features/
},
"observations" : {
"description" : "Observations accessible through this API",
"baseURL" : "https://api.flarecast.eu/observations/
},
...
}
|
File Archive (observations)
The file archive is basically a directory structure from where the files can be loaded either through the file:// protocol or (preferably) the http:// protocol.
| Get list of observation types | |
|---|---|
| Query | |
| Result | {
"sdo_hmi_45" : {
"description" : "SDO HMI LOS",
"baseURL" : "https://api.flarecast.eu/observations/sdo/hmi/$year/$month/$day/$filepattern"
},
"sdo_hmi_720" : { ... }
}
|
| Search for files | |
|---|---|
| Query | https://api.flarecast.eu/observations/sdo/hmi/list?timerange=20150101T000000.0-20150101T120000.0 |
| Result | {
"https://api.flarecast.eu/observations/sdo/hmi/45/2015/01/01/hmi_45_los_00:00:00.fits",
"https://api.flarecast.eu/observations/sdo/hmi/45/2015/01/01/hmi_45_los_00_00_45.fits",
"https://api.flarecast.eu/observations/sdo/hmi/45/2015/01/01/hmi_45_los_00_01_30.fits",
"https://api.flarecast.eu/observations/sdo/hmi/45/2015/01/01/hmi_45_los_00_02_15.fits",
...
}
|
Feature Properties
| Get list of features | |
|---|---|
| Query | https://api.flarecast.eu/features/list |
| Result | {
"id": {
"type": "long"
},
"timestamp": {
"type": "datetime"
},
"area": {
"type": "double",
"unit": "m2",
"version": 5
},
"contour": {
"type": "int[]",
"description": "chaincode, 0 is left, 1-7 is direction counter clockwise",
"version": 1
}
}
|
| Template | |
|---|---|
| Query | https://api.flarecast.eu/features/query?time_begin=20150101T000000.0&time_end=20150101T000000.0&fields=id,timestamp,area,contour |
| Result | {
"id": {
"type": "long"
},
"timestamp": {
"type": "datetime"
},
"area": {
"type": "double",
"unit": "m2",
"version": 5
},
"contour": {
"type": "int[]",
"description": "chaincode, 0 is left, 1-7 is direction counter clockwise",
"version": 1
},
"data": [
[
1,
"2015-01-01T10:20:00.0",
12321,
[0,1,1,1,3,3,4,4,4,4,4,5,5,6,6,7,7,7,7,0]
],
[
2,
"2015-01-01T10:20:45.0",
14412,
[0,1,1,1,3,3,4,4,4,4,4,5,5,6,6,7,7,7,7,0]
],
[
3,
"2015-01-01T10:21:30.0",
14434,
[0,1,1,1,3,3,4,4,4,4,4,5,5,6,6,7,7,7,7,0]
]
]
}
|
Template
| Template | |
|---|---|
| Query | |
| Result | |