OH Auto Statistical REST API¶

Version 0.2

Analyses¶

POST /api/v0/analyses/¶

Submits an OH Auto Statistical analysis to be undertaken asynchronously. Returns a Location header with a URL to retrieve the analysis task status.

Form Parameters:
	(any) – `.xml` catchment file (any) – `.am` annual maximum flow data file (optional) nrfa-id – NRFA gauging station number (optional, to be used instead of catchment files)
Request Headers:
	Authorization – OAuth2 Bearer token for authentication
Response Headers:
	Content-Type – application/json Location – URL to retrieve task status
Status Codes:	202 Accepted – Analysis task accepted 400 Bad Request – Uploaded files invalid 401 Unauthorized – Authentication error

Request:

POST /api/v0/analyses/ HTTP/1.0
Accept: */*
Authorization: Bearer secrettoken
Host: localhost:5000

Response:

HTTP/1.0 202 ACCEPTED
Content-Type: application/json
Content-Length: 3
Location: http://localhost:5000/api/v0/analysis-tasks/124cce24-b02f-4ad8-9475-e8826fb4e655
Server: Werkzeug/0.10.4 Python/3.4.3
Date: Thu, 05 Nov 2015 17:45:04 GMT

GET /api/v0/analyses/(task_id)¶

Returns the OH Auto Statistical analysis report as Markdown-formatted text using the completed task’s task_id. Note that this endpoint does not need to be called explicitly as the task status will redirect to here.

Response Headers:
Parameters:	task_id – Task identifier
	Content-Type – text/plain; charset=utf-8 (analysis report) application/json (error message)
Status Codes:	200 OK – Report successfully returned 404 Not Found – Not a completed analysis task for `task_id`

Response:

HTTP/1.0 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 6412
Server: Werkzeug/0.10.4 Python/3.4.3
Date: Thu, 05 Nov 2015 19:16:01 GMT

# Flood Estimation Report

Date:          05/11/2015
Software:      OH Auto Statistical version 0.8.0

## Input data

River:         Urr
(...)

Analysis tasks¶

GET /api/v0/analysis-tasks/(task_id)¶

If the analysis task is not yet completed the task’s status is returned (json). Otherwise redirects to the analysis report itself.

Response Headers:
Parameters:	task_id – Task identifier
	Content-Type – application/json Location – URL to retrieve task results (when completed)
Status Codes:	200 OK – Status successfully returned 303 See Other – Redirect to `/api/v0/analyses/(task_id)`

Request:

GET api/v0/analysis-tasks/124cce24-b02f-4ad8-9475-e8826fb4e655 HTTP/1.0
Accept: */*
Host: localhost:5000

Response (task in progress):

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 56
Server: Werkzeug/0.10.4 Python/3.4.3
Date: Thu, 05 Nov 2015 20:06:26 GMT

{
    "message": "",
    "state": "PROGRESS"
}

Response (task completed):

HTTP/1.0 303 OK
Content-Type: application/json
Content-Length: 3
Location: http://localhost:5000/api/v0/analysis/124cce24-b02f-4ad8-9475-e8826fb4e655
Server: Werkzeug/0.10.4 Python/3.4.3
Date: Thu, 05 Nov 2015 20:06:30 GMT

Data imports¶

POST /api/v0/data-imports/¶

Load new data into the peak flow database by providing a URL for a zip file of .cd3 and .am files. The zip file is retrieved and files are parsed and then inserted (update) into the database.

Request Headers:
	Content-Type – application/json Authorization – OAuth2 Bearer token for authentication
Status Codes:	202 Accepted – Import task accepted 400 Bad Request – Invalid request body 401 Unauthorized – Authentication error 403 Forbidden – Authorisation error

Request:

POST /api/v0/data-imports/ HTTP/1.0
Accept: */*
Authorization: Bearer secrettoken
Content-Type: application/json
Host: localhost:5000

{
    "url": "https://github.com/OpenHydrology/flood-data/archive/master.zip"
}

Response:

HTTP/1.0 202 ACCEPTED
Content-Type: application/json
Content-Length: 3
Server: Werkzeug/0.10.4 Python/3.4.3
Date: Thu, 05 Nov 2015 17:45:04 GMT