- The API must be made available using SSL-secured HTTP connection (HTTPS).
- The requests must be done using HTTP POST method.
- The API service must accept compressed HTTP request/response operations (gzip).
- The requests must include request parameter called "apikey" used for authenticating the request.
- The Dashboard user creates one or more non-modifiable API keys which are authorised to update variables for one or more resources. Any of these API keys can be removed at any point, after which they are no longer accepted. Typically the user would generate a separate API key to be used by each of the external applications she/he wants to authorise for submitting updates.
- The ancillary/extra information variable values must be bound to a identified resource known to the Dashboard. The type of resource is one of "service", "dataset" or "datasetSeries". If at least one of the resource identifiers given by the external application is not previously known to the Dashboard or is not permitted to be updated with the used API key, the API must discard the entire submission document and return with "resultCode" property value "forbidden" (see Response).
- The Dashboard user with rights to modify the variables for the resources can enable the API for those resources.
The payload of the POST request is a valid JSON document adhering to following the rules (see the attachment "a1_submission_example.json"):
- One update document contains variable data for one or more resources, with one or more variables and one or more time periods or instances.
- The "existingValues" property could be used for controlling collisions with previously provided values for the given resources, variables and time periods / instances.
- Value "replace" value would replace any existing values for the exactly matching resourceId, variableId and timePeriod/timeInstance triples with the new values.
- Value "discard" would keep all the existing values for these triples.
- If a matching resource/variable combination exists with an overlapping, but not exactly the same timePeriod, and the time resolutions and origins for both are same (whole months starting from the first day, whole weeks starting from monday ect.), then the "existingValues" instruction must be applied to each overlapping time step separately. If the time resolutions and/or their origins are different, the submission must be discarded with resultCode "badRequest" (see Response).
- For each resource-varible pair in a document the variable values can be given a one timePeriod object, one timeInstance property or one timeSeries object.
- The value of timeSeries is an array of timePeriod objects or timeInstance properties.
- The value of a timeInstance property is an ISO 8601 date with only the date part allowed (2014-09-01). The start and end properties of timePeriod object are mandatory and have ISO 8601 date-only values. The start and end dates are inclusive.
- The minimum variable data time resolution is one day.
- The value of "value" property is either a JSON number, JSON boolean (true/false) or a JSON string with one of the enumerated values specified for this variable enclosed in double quotes. The acceptable value ranges or options are specific to the used variable.
The API must respond with HTTP status 200 and a valid JSON document adhering to following rules (see attachments "a2_response_example.json" and "a3_response_example_fail.json"):
- The property "processedBy" must indicate the name and version of the receiving application.
- The property "processTime": must indicate time when the service finished processing the submission.
- The "resultCode" property must have one of the following values:
- "ok": the submission was completed successfully.
- "badRequest": The format of the submitted data was not correct. The service should try to return an error message with indications of which parts of the content failed the format check.
- "unauthorized": the username/API key combination does not exist or is no longer valid.
- "forbidden": the username/API key is valid but the request contains at least one resource/variable pair that are not allowed to be updated with this API key. The server should return an error message with the identifier(s) with no update authorisation.
- The if the resultCode is "badRequest" or "forbidden" response must include array valued property "failedResources" containing the resourceIds used in the submission for the updates that caused the submission to fail. For other resultCodes any given values for "failedResources" should be ignored by the submitting application.
- The "message" property may include a human-readable explanation of the possible errors occurred or a success statement if is resultCode is "ok".
The API may also respond with any other valid HTTP status than 200, but in this case the submitting application should assume that no information was stored.