POST institution environment - ocariot/api-gateway GitHub Wiki

Description

Permissions:

An Application can register an Environment and associate it with an Institution as long as that Institution exists.

Scope

environment:create

URL

POST https://localhost/v1/institutions/{institution_id}/environments

Parameters

institution_id: string (A 24-byte hex ID)

Request body

{
  "institution_id": "5a62be07de34500146d9c544",
  "location": {
    "local": "indoor",
    "room": "Bloco H sala 01",
    "latitude": -7.2100766,
    "longitude": -35.9175756
  },
  "measurements": [
    {
      "type": "temperature",
      "value": 35.6,
      "unit": "°C"
    },
    {
      "type": "humidity",
      "value": 42.2,
      "unit": "%"
    },
    {
      "type": "pm1",
      "value": 0.57,
      "unit": "µm"
    },
    {
      "type": "pm2.5",
      "value": 1.9,
      "unit": "µm"
    },
    {
      "type": "pm10",
      "value": 7.9,
      "unit": "µm"
    }
  ],
  "climatized": true,
  "timestamp": "2019-11-19T14:40:00Z"
}

Curl example

curl -X POST "https://localhost/v1/institutions/5a62be07de34500146d9c624/environments" -H "accept: application/json" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d "{"location":{"local":"indoor","room":"Bloco H sala 01","latitude":"-7.2100766","longitude":"-35.9175756"},"measurements":[{"type":"temperature","value":35.6,"unit":"°C"},{"type":"humidity","value":42.2,"unit":"%"},{"type":"pm1","value":0.57,"unit":"µm"},{"type":"pm2.5","value":1.9,"unit":"µm"},{"type":"pm10","value":7.9,"unit":"µm"}],"climatized":true,"timestamp":"2018-11-19T14:40:00Z"}"

Response body

201 Environment measurement saved sucessfully.

{
  "id": "5a62be07de34500146d9c544",
  "institution_id": "5a62be07de34500146d9c544",
  "location": {
    "local": "indoor",
    "room": "Bloco H sala 01",
    "latitude": -7.2100766,
    "longitude": -35.9175756
  },
  "measurements": [
    {
      "type": "temperature",
      "value": 35.6,
      "unit": "°C"
    },
    {
      "type": "humidity",
      "value": 42.2,
      "unit": "%"
    },
    {
      "type": "pm1",
      "value": 0.57,
      "unit": "µm"
    },
    {
      "type": "pm2.5",
      "value": 1.9,
      "unit": "µm"
    },
    {
      "type": "pm10",
      "value": 7.9,
      "unit": "µm"
    }
  ],
  "climatized": true,
  "timestamp": "2019-11-19T14:40:00Z"
}

207 Successful request, however, can have several status codes for the case of a list of submitted environment records.

{
  "success": [
    {
      "code": 201,
      "item": {
          "id": "5a62be07de34500146d9c544",
          "institution_id": "5a62be07de34500146d9c544",
          "location": {
            "local": "indoor",
            "room": "Bloco H sala 01",
            "latitude": -7.2100766,
            "longitude": -35.9175756
          },
          "measurements": [
            {
              "type": "temperature",
              "value": 35.6,
              "unit": "°C"
            },
            {
              "type": "humidity",
              "value": 42.2,
              "unit": "%"
            },
            {
              "type": "pm1",
              "value": 0.57,
              "unit": "µm"
            },
            {
              "type": "pm2.5",
              "value": 1.9,
              "unit": "µm"
            },
            {
              "type": "pm10",
              "value": 7.9,
              "unit": "µm"
            }
          ],
          "climatized": true,
          "timestamp": "2019-11-19T14:40:00Z"
      }
    }
  ],
  "error": [
    {
      "code": 409,
      "message": "Environment is already registered...",
      "item": {
        "institution_id": "5a62be07de34500146d9c544",
        "location": {
          "local": "indoor",
          "room": "Bloco H sala 01",
          "latitude": -7.2100766,
          "longitude": -35.9175756
        },
        "measurements": [
          {
            "type": "temperature",
            "value": 35.6,
            "unit": "°C"
          },
          {
            "type": "humidity",
            "value": 42.2,
            "unit": "%"
          },
          {
            "type": "pm1",
            "value": 0.57,
            "unit": "µm"
          },
          {
            "type": "pm2.5",
            "value": 1.9,
            "unit": "µm"
          },
          {
            "type": "pm10",
            "value": 7.9,
            "unit": "µm"
          }
        ],
        "climatized": true,
        "timestamp": "2019-11-20T14:40:00.000Z"
      }
    }
  ]
}

400 Validation errors

Invalid JSON format
Invalid institution id
Institution does not exist

Missing fields

Example

{
  "code": 400,
  "message": "Required fields were not provided...",
  "description": "timestamp, institution_id, location, measurements are required!"
}

Invalid timestamp

Empty measurements array

Example

{
  "code": 400,
  "message": "One or more request fields are invalid...",
  "description": "measurements collection must not be empty!"
}

Naming pattern of location attribute (for the following two error patterns)
```
location.local
location.room
location.latitude
location.longitude
```

Empty string

Example

{
  "code": 400,
  "message": "One or more request fields are invalid...",
  "description": "measurements.type must have at least one character!"
}

Invalid string

Example

{
  "code": 400,
  "message": "One or more request fields are invalid...",
  "description": "measurements.unit must be a string!"
}

Invalid number

Example

{
  "code": 400,
  "message": "One or more request fields are invalid...",
  "description": "measurements.value must be a valid number!"
}

Invalid climatized attribute

Example

{
  "code": 400,
  "message": "One or more request fields are invalid...",
  "description": "climatized must be a boolean!"
}

401 Unauthorized Error
403 Permission Error
409 Conflict Error
429 Too Many Requests Error
500 Internal Server Error