BaltradDex
BALTRAD Data Exchange System
Loading...
Searching...
No Matches
Data exchange format
Date
December 30, 2015
Version
2.2

Index

  1. General information
  2. Authentication
    1. Authentication header
    2. Signing a request
  3. Data source listing request
  4. Start subscription request
  5. Update subscription request
  6. Post key request
  7. Post file request
  8. Post message request

General information

BaltradDex uses standard HTTP message structure for communication. Request and response parameters are passed as HTTP message headers. However, for passing additional information between BALTRAD nodes, the following custom header fields are introduced:

Node-Name: <name of requesting node>
Provider: [Peer|Injector]

This information is essential for correct node identification within BALTRAD network, as well as for message authentication.

Attention
Provider header is applied to Post file request and allows to distinguish between request coming from the peer node and request sent by the injector, that is third-party software providing data from local production system. It should take one of the following values: Injector in case of a request send by an injector software, and Peer in case of a request sent by the peer node.

Authentication


For safety reasons, all messages passed within BALTRAD network are authenticated. Authentication is based on private/public keys using KeyCzar toolkit.

Authentication header

For the purpose of authentication, a standard HTTP Authorization header is used. The header value consists of user name name and user-specific credentials in the following format:

Authorization: <user name>:<credentials>
Attention
User name is used to locate and access keys in the keystore. By default, BaltradDex uses node name property for this purpose. Therefore node name provided at the stage of installation (or initialization of the keystore) should not be modified without a justified reason.

Signing a request

In order to sign a request, first an input message should be prepared. This message will be next used to generate a signature. Input message is assembled from the following request elements: 

    - Request method 
    - Request URI
    - Content-Type request header
    - Content-MD5 request header
    - Date

Typical input message will look like the following:

GET
http://example.baltrad.eu:8084/BaltradDex/get_datasource_listing.htm
text/html
aHR0cDovLzE ...
Fri, 6 Jul 2012 13:00:26 CEST
Attention
The value of Content-MD5 request differs depending on the type of request. Refer to the documentation of particular request types for details.

Input message is signed with KeyCzar sign() method available in org.keyczar.Signer class, resulting in Base64 encoded signature string. Exemplary authorization header will take the following form:

Authorization: example.baltrad.eu:APa7608wLQI ...

Once signed, the request is ready to submit. In case of a failure to authenticate the request on server side, the server will response with HTTP 401 Unauthorized status code. In case the server is unable to find a public key matching user name provided in Authorization header, HTTP 500 Internal Server Error response is returned.

Data source listing request

Description

Request for data source listing. Reponse contains list of data sources available for a given user to subscribe.
Request
  • Request URI: datasource_listing.htm
  • Method: POST
  • Headers: Node-Name, Content-Type, Content-MD5, Date, Authorization
  • Body: Subscriber node's credentials

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/datasource_listing.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Content-Type: application/json
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    {
    "name":"baltrad.imgw.pl",
    "nodeAddress":"http://baltrad.imgw.pl:8084",
    "orgName":"Institute of Meteorology and Water Management",
    "orgUnit":"Remote Sensing Department",
    "locality":"Warsaw",
    "state":"Poland",
    "countryCode":"PL"
    }
Note
Content-MD5 header value consists of Base64-encoded request URI.
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success - data sources subscribed
      • 201 Created : Success - user account established
    • 401 Unauthorized : Server failed to authenticate request
    • 500 Internal server error : Server error
  • Body:
    • 201 : User account credentials
    • 200 : List of subscribed data sources

  • Example 201 response:
    Node-Name: baltrad-backup.imgw.pl
    {
    "name":"baltrad.imgw.pl",
    "nodeAddress":"http://baltrad.imgw.pl:8084",
    "orgName":"Institute of Meteorology and Water Management",
    "orgUnit":"Remote Sensing Department",
    "locality":"Warsaw",
    "state":"Poland",
    "countryCode":"PL"
    }
  • Example 200 response:
    Node-Name: baltrad-backup.imgw.pl
    [
    {
    "name":"PoznańSCAN",
    "type":"peer",
    "description":"Polar scans from Poznań"
    },
    {
    "name":"LegionowoPVOL",
    "type":"peer",
    "description":"Polar volumes from Legionowo"
    },
    {
    "name":"PastewnikALL",
    "type":"peer",
    "description":"Polar scans and volumes from Pastewnik"
    }
    ]

Start subscription request

Description

Request for data source subscription. Reponse contains list of successfully subscribed data sources.
Request
  • Request URI: start_subscription.htm
  • Method: POST
  • Headers: Node-Name, Content-Type, Content-MD5, Date, Authorization
  • Body: List of data sources selected for subscription

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/start_subscription.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Content-Type: application/json
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    [
    {
    "name":"PoznańSCAN",
    "type":"peer",
    "description":"Polar scans from Poznań"
    },
    {
    "name":"LegionowoPVOL",
    "type":"peer",
    "description":"Polar volumes from Legionowo"
    }
    ]
Note
Content-MD5 header value consists of Base64-encoded list of data sources selected for subscription.
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success
    • 206 Partial Content : Subscription request was completed partially
    • 401 Unauthorized : Server failed to authenticate request
    • 404 Not Found : Generic subscription error
    • 500 Internal server error : Server error
  • Body: List of successfully subscribed data sources

  • Example:
    Node-Name: baltrad-backup.imgw.pl
    [
    {
    "name":"PoznańSCAN",
    "type":"peer",
    "description":"Polar scans from Poznań"
    },
    {
    "name":"LegionowoPVOL",
    "type":"peer",
    "description":"Polar volumes from Legionowo"
    }
    ]

Update subscription request

Description

Request for subscription update. Reponse contains list of updated subscriptions.
Request
  • Request URI: update_subscription.htm
  • Method: POST
  • Headers: Node-Name, Content-Type, Content-MD5, Date, Authorization
  • Body: List of subscriptions

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/update_subscription.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Content-Type: application/json
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    [
    {
    "type":"local",
    "date":1357909585672,
    "active":true,
    "dataSource":"LegionowoPVOL",
    "user":"baltrad.imgw.pl",
    "syncronized":true
    },
    {
    "type":"local",
    "date":1357909585757,
    "active":true,
    "dataSource":"PoznańSCAN",
    "user":"baltrad.imgw.pl",
    "syncronized":true
    }
    ]
Note
Content-MD5 header value consists of Base64-encoded list of subscriptions.
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success
    • 206 Partial Content : Subscription request was completed partially
    • 401 Unauthorized : Server failed to authenticate request
    • 404 Not Found : Generic subscription error
    • 500 Internal server error : Server error
  • Body: List of successfully updated subscriptions

  • Example:
    Node-Name: baltrad-backup.imgw.pl
    [
    {
    "type":"local",
    "date":1357909625659,
    "active":true,
    "dataSource":"LegionowoPVOL",
    "user":"baltrad.imgw.pl",
    "syncronized":true
    },
    {
    "type":"local",
    "date":1357909625706,
    "active":true,
    "dataSource":"PoznańSCAN",
    "user":"baltrad.imgw.pl",
    "syncronized":true
    }
    ]

Post key request

Description

Post key request. Reponse indicates post key operation result.
Request
  • Request URI: post_key.htm
  • Method: POST
  • Headers: Node-Name, Content-Type, Content-MD5, Date, Authorization
  • Body: Key content

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/post_key.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Content-Type: application/zip
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    <key content>
Note
Content-MD5 header value consists of MD5-encoded key content as hexadecimal string. \endnote
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success
    • 401 Unauthorized : Server failed to authenticate request
    • 409 Conflict : Key already exists on server
    • 500 Internal server error : Server error
  • Body: No content

  • Example:
    Node-Name: baltrad-backup.imgw.pl

Post file request

Description

Post file request. Reponse indicates post file operation result.
Request
  • Request URI: post_file.htm
  • Method: POST
  • Headers: Node-Name, Provider, Content-Type, Content-MD5, Date, Authorization
  • Body: File content

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/post_file.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Provider: Peer
    Content-Type: application/x-hdf5
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    <file content>
Note
Content-MD5 header value consists of Base64-encoded request URI.
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success
    • 401 Unauthorized : Server failed to authenticate request
    • 404 Not Found : Generic post file error
    • 409 Conflict : File already stored in the database
    • 500 Internal server error : Server error
  • Body: No content

  • Example:
    Node-Name: baltrad-backup.imgw.pl

Post message request

Description

Post message request. Message body is processed by Beast messaginng interface. Reponse indicates post message operation result.
Request
  • Request URI: post_message.htm
  • Method: POST
  • Headers: Node-Name, Content-Type, Content-MD5, Date, Authorization
  • Body: Message string

  • Example:
    POST http://baltrad.imgw.pl:8084/BaltradDex/post_message.htm HTTP/1.1
    Node-Name: baltrad.imgw.pl
    Content-Type: text/html
    Content-MD5: aHR0cDovLzE ...
    Date: Fri, 6 Jul 2012 13:00:26 CEST
    Authorization: baltrad.imgw.pl:APa7608wLQI ...
    <Message body>
Note
Content-MD5 header value consists of Base64-encoded message body.
Response
  • Headers: Node-Name
  • Status:
    • 200 OK : Success
    • 401 Unauthorized : Server failed to authenticate request
    • 500 Internal server error : Server error / Unsupported message format
  • Body: No content

  • Example:
    Node-Name: baltrad-backup.imgw.pl
Attention
Because message body is processed by Beast messaging interface, its format should match XML-based message format defined by Beast. In case of attempt to pass a message of unsupported format, the server will respond with Internal Server Error (500). Refer to Beast framework documentation for details.