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.

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,

Standards

Dates should be in ISO 8601
Date/Time formats should follow http://www.w3.org/TR/NOTE-datetime
URI Templates: https://tools.ietf.org/html/rfc6570
Collection+JSON: http://amundsen.com/media-types/collection/
IANA link relations: http://www.iana.org/assignments/link-relations/link-relations.xhtml

The API is self-documenting such that there a single entry point to all databases.

Resources

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

Get list of observation types

Query

/resources/list

Result

{
	{
    "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/"
    },
	...
 }

Observations

The file archive is basically a directory structure from where the files can be loaded through the http:// protocol.

Get list of available observation types

Query

/observations

Result

{
	"sdo_hmi_720" : {
		"description" : "SDO HMI",
		"baseURL" : "https://api.flarecast.eu/observations/sdo/hmi/fits/",
		"filepattern": "${YYYY}/${MM}/${DD}/hmi.M_720s_nrt.${YYMMDD}_${nr}_TAI.fits",
		"timeBegin": "2015-01-01T00:00:00Z",
		"timeEnd": "2015-04-20T00:00:00Z"
    },
	"sdo_hmi_45" : { ... }
}

Search for files

Query

/observations/sdo/hmi/list?timerange=20150101T000000.0-20150101T120000.0

Result

{
	"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

/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

//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

Query

Result

2012-04-23T18:25:43.511Z