POST institution environment

Description

Register a new environment measurement and associate it to an Institution.

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