Skip to content
This repository has been archived by the owner on Apr 7, 2020. It is now read-only.

Latest commit

 

History

History
485 lines (366 loc) · 10.2 KB

API-description.md

File metadata and controls

485 lines (366 loc) · 10.2 KB
Raw

API description

All routes should be prefixed with 'api/v1'.

POST measurements/new

Send one or more measurements using [measurement data protocol]. If timestamp is equal to 2004-01-01, it will be ignored and measurement's collectedAt property will be set as current local time in Brazil/East timezone.

Parameters:

  • sensorIdentifier: string (required)
  • data: string (required)

Possible responses:

  • 200 Success and list of measurements:
  • 400 Bad request and errors JSON;
  • 404 Sensor not found.

Example request for a sensor with '5555' as identifier:

curl 'http://localhost:3000/api/v1/measurements/new' \
     -H "Content-Type: application/json" \
     --data-binary \
      '{"sensorIdentifier":"5555","data":"2015-08-01T10:08:15-03:00;Tw=20.3;Ta:F=78.29;pH=6.9"}' \
     --compressed

A list of measurements will be return as JSON, with HTTP status code 200 (success):

{
    "measurements": [{
        "__v": 0,
        "sensor": {
            "_id": "55c3af3e8037a34d53461da8",
            "name": "Sensor de teste",
            "identifier": "5555",
            "__v": 0,
            "createdAt": "2015-08-06T19:02:22.989Z",
            "geometry": {
                "coordinates": [{
                    "0": "1",
                    "1": "1"
                }]
            }
        },
        "collectedAt": "2015-08-01T13:08:15.000Z",
        "parameter": "water_temperature",
        "unit": null,
        "value": 20.3,
        "_id": "55c4ba47b01be2cb5b3c76b0"
    }, {
        "__v": 0,
        "sensor": {
            "_id": "55c3af3e8037a34d53461da8",
            "name": "Sensor de teste",
            "identifier": "5555",
            "__v": 0,
            "createdAt": "2015-08-06T19:02:22.989Z",
            "geometry": {
                "coordinates": [{
                    "0": "1",
                    "1": "1"
                }]
            }
        },
        "collectedAt": "2015-08-01T13:08:15.000Z",
        "parameter": "sensor_temperature",
        "unit": "F",
        "value": 78.29,
        "_id": "55c4ba47b01be2cb5b3c76b1"
    }, {
        "__v": 0,
        "sensor": {
            "_id": "55c3af3e8037a34d53461da8",
            "name": "Sensor de teste",
            "identifier": "5555",
            "__v": 0,
            "createdAt": "2015-08-06T19:02:22.989Z",
            "geometry": {
                "coordinates": [{
                    "0": "1",
                    "1": "1"
                }]
            }
        },
        "collectedAt": "2015-08-01T13:08:15.000Z",
        "parameter": "ph",
        "unit": null,
        "value": 6.9,
        "_id": "55c4ba47b01be2cb5b3c76b2"
    }]
}

Users

Account

Sensors

Measurements

Users

GET account

Gets account information.

Possible responses:

  • 200 Success + user object json;
  • 401 Unauthorized;
  • 500 Internal error.

PUT account

Updates account information.

Parameters:

  • name: string
  • email: string
  • phoneNumber: string
  • password: string
  • oldPassword: string (required when password is provided)

Possible responses:

  • 200 Success + user object json;
  • 400 Bad request;
  • 401 Unauthorized;
  • 500 Internal error.

GET users

Get a list of users, needs authentication and admin role.

Parameters:

  • perPage: number (default: 20)
  • page: number (optional)

Possible responses:

  • 200 Success and list of users:
  • 400 Bad request.
  • 401 Unauthorized.

POST users

Creates a user. The first created user will have admin role.

Parameters:

  • name: string
  • email: string
  • phoneNumber: string
  • password: string

Possible responses:

  • 200 Success + user object json;
  • 400 Bad request;
  • 401 Unauthorized;
  • 500 Internal error.

GET users/:user_id

Get user details.

Parameters:

  • :user_id: string (required)

Possible responses:

  • 200 Success and JSON:
  • 400 Bad request.
  • 401 Unauthorized.

PUT users/:user_id

Route for admins to update account details of another user.

Parameters:

  • role: string admin or subscriber
  • name: string
  • email: string
  • phoneNumber: string
  • password: string

Possible responses:

  • 200 Success + user object json;
  • 400 Bad request;
  • 401 Unauthorized;
  • 500 Internal error.

DEL users/:user_id

Delete user.

Needs authentication and "admin" role.

Possible responses:

  • 200 Success;
  • 401 Unauthorized;
  • 404 Not found;
  • 500 Internal error.

Sensors

GET sensors

Get a list of sensors.

Parameters:

  • perPage: number (default: 20)
  • page: number (optional)

Possible responses:

  • 200 Success and list of sensors:
  • 400 Bad request.

POST sensors

Creates a new sensor.

Parameters:

  • identifier: string phone number or mac address (required)
  • name: string sensor's name (required)
  • description: string sensor's description
  • image: string an image url

Possible responses:

  • 201 Success + sensor object json;
  • 400 Bad request.
  • 401 Unauthorized;

GET sensors/:sensor_id

Get information about a single sensor.

Parameters:

  • :sensor_id: string (required)

Possible responses:

  • 200 Success + sensor object json;
  • 400 Bad request;
  • 404 Not found.

PUT sensors/:sensor_id

Updates sensor information.

Parameters:

  • :sensor_id string
  • identifier: string phone number or mac address (required)
  • name: string (required)
  • description: string
  • image: string an image url

Possible responses:

  • 201 Success + sensor object json;
  • 400 Bad request;
  • 401 Unauthorized;
  • 404 Not found.

DEL sensors/:sensor_id

Destroy sensor and all measurements related to the it.

Parameters:

  • :sensor_id string

Possible responses:

  • 200 Success;
  • 400 Bad request;
  • 401 Unauthorized;
  • 404 Not found.

POST sensors/:sensor_id/subscribe

Subscribes user to sensor.

Needs authentication.

Parameters:

  • :sensor_id: string (required)

Possible responses:

  • 200 Success + user json;
  • 401 Unauthorized;
  • 404 Not found;
  • 500 Internal error.

POST sensors/:sensor_id/unsubscribe

Unsubscribes user to sensor.

Needs authentication.

Parameters:

  • :sensor_id: string (required)

Possible responses:

  • 200 Success + user json;
  • 401 Unauthorized;
  • 404 Not found;
  • 500 Internal error.

GET sensors/:sensor_id/measurements/:parameter_id.csv

Download all measurements as CSV file. Example:

http://rede.infoamazonia.org/sensor/1203910293029/measurements/atmospheric_pressure.csv

Possible responses:

  • 200 Success + CSV file;
  • 404 Not found;
  • 500 Internal error.

GET parameters

Returns a list of parameters.

Response:

  • 200 Success status and parameters as json:

DEL measurements/:measurement_id

Destroy measurement.

Parameters:

  • :measurement_id string

Possible responses:

  • 200 Success;
  • 400 Bad request;
  • 401 Unauthorized;
  • 404 Not found.

GET measurements

Returns a list of measurements.

Parameters:

  • sensor_id: string (required)
  • parameter_id: string (optional)
  • perPage: number (default: 20)
  • page: number (optional)
  • fromDate: string [ISO 8601] timestamp
  • toDate: string [ISO8601] timestamp

Possible responses:

  • 200 Success and list of measurements:
  • 400 Bad request.

GET measurements/aggregate

Returns a measurements aggregate. Due to a MongoDB limitation, all measurements are recorded in UTC and timezone are discarded.

Parameters:

  • sensor_id: string (required)
  • parameter_id: string (required)
  • resolution: 'month','week', 'day' or 'hour' (optional, default: 'day')
  • fromDate: string [ISO 8601] (optional, default: 10 days from now)
  • toDate: string [ISO 8601] (optional, default: now)

Possible responses:

  • 200 Success and list of measurements:
  • 400 Bad request.

Example response:

{
    "sensor_id": "55c9152f2e11aa7f1248125a",
    "parameter_id": "atmospheric_pressure",
    "start": "2015-07-31T21:18:40.142Z",
    "end": "2015-08-10T21:18:40.142Z",
    "aggregates": [{
        "_id": {
            "year": 2015,
            "month": 8,
            "day": 7
        },
        "max": 79270.70534555241,
        "avg": 79270.70534555241,
        "min": 79270.70534555241
    }, {
        "_id": {
            "year": 2015,
            "month": 8,
            "day": 8
        },
        "max": 102476.60015244037,
        "avg": 52827.800702361856,
        "min": 871.2151763029397
    }, {
        "_id": {
            "year": 2015,
            "month": 8,
            "day": 9
        },
        "max": 99783.68117124774,
        "avg": 56159.60560477106,
        "min": 3322.4598434753716
    }, {
        "_id": {
            "year": 2015,
            "month": 8,
            "day": 10
        },
        "max": 101622.79594223946,
        "avg": 47760.78379411378,
        "min": 1971.235773526132
    }]
}

GET measurements/group

Returns measurements grouped by collectedAt.

Parameters:

  • sensor_id: string (required)

Possible responses:

  • 200 Success and list of measurements:
  • 400 Bad request.