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

The following standards should be considered.

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
IANA link relations: http://www.iana.org/assignments/link-relations/link-relations.xhtml

The current proposal is based on http://jsonapi.org/

The corresponding IANA registered media type is: application/vnd.api+json.

Resources

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

Get list of observation types

Request

Replace

var	restBaseUrl

/resources

Result

Code Block

language	js
title	application/vnd.api+json

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type" : "resources", 
    "id" : "person",
    "title": "A person",
    "links": { 
      "self" : "https://api.flarecast.eu/v1/persons/"
     }
  }, {
    "type" : "resources", 
    "id" : "algorithm",
    "title": "Algorithm or other software artifact",
    "links": { 
      "self" : "https://api.flarecast.eu/v1/algorithms/"
    }
  }, {
    "type" : "resources", 
    "id" : "feature",
    "title": "Features accessible through this API",
    "links": { 
      "self" : "https://api.flarecast.eu/v1/features/"
    }
  }, {
    "type" : "resources", 
    "id" : "observation_types",
    "title": "Types of observations accessible through this API",
    "links": {
       "self" : "https://api.flarecast.eu/v1/observation_types/"
    },
  }, 
  ...
  ]
}

Code Block

language	js
title	Homegrown

HTTP/1.1 200 OK
Content-Type: application/flarecast+json

{    
  "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_types" : {
    "description" : "Type of observations accessible through this API",
    "baseURL" : "https://api.flarecast.eu/observation_types/"
  },
  ...
}

Observations

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

Get list of available observation types

Request

Replace

var	restBaseUrl

/observation_types

Result

Code Block

title	application/vnd.api+json

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data" : [{
    "type" : "observation_types",
    "id" : "sdo_hmi_720",
    "description" : "SDO HMI",
    "links": {
	   "self" : "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"
  }, {
    "type" : "observation_types",
    "id" : "sdo_hmi_45",
    ...,
  }
}

Code Block

language	js
title	Home grown

HTTP/1.1 200 OK
Content-Type: application/flarecast+json

{
	"sdo_hmi_720" : {
		"description" : "SDO HMI",
		"baseURL" : "https://api.flarecast.eu/observation_types/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

Request

Replace

var	restBaseUrl

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

Result

Code Block

language	js

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

Request

Replace

var	restBaseUrl

/features/list

Result

Code Block

language	js

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

Get features in a timerange

Request

Replace

var	restBaseUrl

//features/query?time_begin=20150101T000000.0&time_end=20150101T000000.0&fields=id,timestamp,area,contour

Result

Code Block

language	js

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

Request

Result

Code Block

language	js

2012-04-23T18:25:43.511Z

Documentation

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

Space shortcuts

Page tree

Versions Compared

Old Version 25

New Version Current

Key

Standards

Resources

Observations

Feature Properties

Template

Documentation

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 25

New Version Current

Key

Standards

Resources

Observations

Feature Properties

Template

Documentation