WP4: Infrastructure
Space shortcuts
Page tree

Versions Compared

Old Version 7

changes.mady.by.user Marco Soldati

Saved on

compared with

New Version Current

changes.mady.by.user Marco Soldati

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 logical databases. All of these databases store different types of resources.

DatabaseResource
Data ArchiveObservation (e.g. FITS-Files)
Staging TableEvent, ... (e.g. Event lists)
Feature Property DatabaseFeature (such as Active Regions), FeatureProperty (e.g. Area, Contour, Zurich-Class, ...)
Predictions Config DBScalars, Vectors, Matrices (e.g. Algo-Configurations)
Prediction DB?
Infrastructure Configuration DBAlgorithm, Person,

 

The API is self-documenting such that there a single entry point to all databases. This would be access to the resources.

Resources

Anything accessible through the API is a "resource". All available resources can be listed.

Get list of observation types
Queryhttps://api.flarecast.eu/resources/list
Result
Code Block
languagejs
{
	{
    "people" : {
        "description": "Persons or groups responsible",
        "baseURL": "https://api.flarecast.eu/people/"
    },
    "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

https://api.flarecast.eu/observations/list

Result
Code Block
languagejs
{
	"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
Code Block
languagejs
{
	"https://api.flarecast.eu/observations/sdo/hmi/fits/2015/04/20/hmi.M_720s_nrt.20150420_010000_TAI.fits",
	"https://api.flarecast.eu/observations/sdo/hmi/fits/2015/04/20/hmi.M_720s_nrt.20150420_020000_TAI.fits",
	"https://api.flarecast.eu/observations/sdo/hmi/fits/2015/04/20/hmi.M_720s_nrt.20150420_030000_TAI.fits",
	...
}

Feature Properties

 

Get list of features
Query https://api.flarecast.eu/features/list
Result
Code Block
languagejs
{
    "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
Queryhttps://api.flarecast.eu/features/query?time_begin=20150101T000000.0&time_end=20150101T000000.0&fields=id,timestamp,area,contour 
Result
Code Block
languagejs
{
    "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
Code Block
languagejs
 

Standards

The following standards should be considered.

Documentation

The current REST API is defined in Deliverables - 640216_Database schema for active region properties and associated flare events.pdf