Submitting observations to the InfoEx via the CAAML 3.0.3 API

From InfoEx Help Information
Revision as of 19:43, 22 December 2013 by Pascal (talk | contribs) (Submission of observations via CAAML 3.0.3 API)
Jump to navigation Jump to search
REQUIREMENTS
Permission Operation Administrator and higher
Connectivity Online only

This document describes how to submit observations from an external database system to the InfoEx via its CAAML 3.0.3 API. This document is aimed at IT system administrators who are setting up the exchange between the two systems on behalf of the InfoEx subscriber.

Background

To submit to the InfoEx system via the CAAML 3.0.3 API, the operator needs two pieces of information from the CAA:

  • API Key
    A secret token that uniquely identifies the submitting system and provides it with administration privileges for the operation.
  • Operation UUID
    The universally unique identifier of the operation used in the InfoEx system.

Please connect with the InfoEx manager at the Canadian Avalanche Association to get this information for your operation.

The CAAML 3.0.3 API is intended to make the transition of existing data systems that directly submit observations to the new InfoEx as easy as possible. By supporting the submission via the legacy CAAML 3.0.3 file format, the submission procedure of these systems only has to be adjusted minimally for the 2013/14 winter season. As a consequence, however, the InfoEx CAAML 3.0.3 API only supports observation types what were used in the legacy InfoEx system during the 2012/13 winter season. Any of the new functionalities that the new InfoEx system offers (e.g., hazard assessments, PWL tracking) is not supported by this API.

NOTE The CAAML 3.0.3 API will only be made accessible to data systems that already submitted observation directly to the legacy InfoEx system. Any new developments should be using the more advanced JSON API that is used internally by the new InfoEx system or the future CAAML 5.0 API which will both support the full functionality of the new system.

Step-by-step description

Submission of observations via CAAML 3.0.3 API

This section described the different components of the HTTPS POST call

1. HTTPS POST URL

Production server: https://infoex.avalancheassociation.ca/CAAML/v3
Training server: https://training-infoex.avalancheassociation.ca/CAAML/v3

2. HTTP HEADERS

Accept: application/json
operation: <operation-uuid>
api_key: <API_KEY>

3. HTTP POST PAYLOAD (RAW XML UTF-8)

Observations in CAAML 3.0.3 format (see http://caaml.org/Schemas/V3.0.3/ for more information of CAAML 3.0.3).

4. RESPONSE (JSON)

Success: { "message": "OK" }
Error: { "message": "Error Description Here"}
If the message is anything other than "OK", then an error occurred. The message contains a description of the error.

NOTE The payload is treated as a single transaction, so in the event of an error nothing will be committed - the error in the file will need to be corrected and the entire thing re-submitted.

Related documents

  • Link to relate document 1
  • Link to relate document 2

Functionality tested by

  • Dec. 22, 2013: Pascal Haegeli