api_doc.yaml

openapi: 3.0.3


info:
  title: MyClimate API
  version: 1.0.0

servers:
  - url: http://127.0.0.1:8000


tags:
  - name: user
  - name: home
  - name: sensor
  - name: temperature
  - name: prediction






paths:
  /user/login:
    post:
      tags:
        - user
      summary: User log in
      description: User log in. Returns a bearer authentication token.

      requestBody:
        description: User information
        content:
          application/json:

            schema:
              type: object
              properties:

                username:
                  type: string
                  description: >
                    Username of the user.
                    Max length: 60
                    Required: true
                  example: Robert

                password:
                  type: string
                  description: >
                    User's password.
                    Max length: 1024
                    Min length: 4
                    Required: true
                  example: 1234

        required: true

      responses:
        '200':
          description: User is now authenticated with the returned token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth'
        '403':
          description: Forbidden. Passwords do not match.
        '404':
          description: User not found. There is no user with the given username.
        '422':
          description: Validation error. Missing values, too long values...

  /user/register:
    post:
      tags:
        - user
      summary: Register a new user
      description: Register a new user. Username must be unique. Password min length = 4

      requestBody:
        description: User information
        content:
          application/json:
            schema:
              type: object
              properties:

                username:
                  type: string
                  description: >
                    Unique, Max length: 60, Required: True
                  example: Robert

                password:
                  type: string
                  description: >
                    Secure, Max length: 1024 Min length: 4 Required: True
                  example: 1234

        required: true

      responses:
        '201':
          description: A new user has been created. Returns an authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth'

        '422':
          description: Validation error. Username already taken, short password...

  /user/homes:
    get:
      summary: Get all houses of the authenticated user.
      description: Get all houses that owns the authenticated user. Requires authentication.
      tags:
        - user
        - home

      security:
        - bearerAuth: []

      responses:
        '200':
          description: Return user's houses.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        user_id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Mansion
                        address:
                          type: string
                          example: Melon Street 2
                        description:
                          type: string
                          example: House with garden!
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=4
                      last:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=13
                      prev:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=3
                      next:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=5
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 3
                      from:
                        type: integer
                        example: 2
                      last_page:
                        type: integer
                        example: 13
                      links:
                        type: array
                        items:
                          type: object
                          properties:

                            url:
                              type: string
                              example: http://127.0.0.1:8000/homes?page=3
                            label:
                              type: integer
                              example: 3
                            active:
                              type: boolean
                              example: true
                  path:
                    type: string
                    example: http://127.0.0.1:8000/homes
                  per_page:
                    type: integer
                    example: 10
                  to:
                    type: integer
                    example: 4
                  total:
                    type: integer
                    example: 130
        '401':
          description: Requires authentication



  /homes:
    post:
      tags:
        - home
      security:
        - bearerAuth: []
      summary: Creates a new home
      description: >
        Creates a new home with the given data  
        The owner of the home will be the authenticated user.
        Requires authentication.

      requestBody:
        description: Home information
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >
                    ** Name of the house **
                    Max length: 60
                    required: true
                  example: Mansion

                address:
                  type: string
                  description: >
                    Max length: 100
                    required: true
                  example: Duck Street 4

                description:
                  type: string
                  description: >
                    Max length: 500
                    required: true
                  example: 'House with barbecue!'

        required: true

      responses:
        '201':
          description: A new home has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Home'
        '401':
          description: Requires authentication.
        '422':
          description: Validation error, Missing values, incorrect types, too long strings...
    get:
      tags:
        - home
      summary: List all homes.
      description: List all homes, paginated and using optional query parameters. Authentication is required.

      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: id
          schema:
            type: integer
          description: Id of the house
        - in: query
          name: address
          schema:
            type: string
          description: House address, can be just a part of the address.
        - in: query
          name: description
          schema:
            type: string
          description: House description, can be just a part of the description.

      responses:
        '200':
          description: Success. Can return an empty list of houses.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        user_id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: Mansion
                        address:
                          type: string
                          example: Melon Street 2
                        description:
                          type: string
                          example: House with garden!
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=4
                      last:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=13
                      prev:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=3
                      next:
                        type: string
                        example: http://127.0.0.1:8000/homes?page=5
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 3
                      from:
                        type: integer
                        example: 2
                      last_page:
                        type: integer
                        example: 13
                      links:
                        type: array
                        items:
                          type: object
                          properties:

                            url:
                              type: string
                              example: http://127.0.0.1:8000/homes?page=3
                            label:
                              type: integer
                              example: 3
                            active:
                              type: boolean
                              example: true
                  path:
                    type: string
                    example: http://127.0.0.1:8000/homes
                  per_page:
                    type: integer
                    example: 10
                  to:
                    type: integer
                    example: 4
                  total:
                    type: integer
                    example: 130

        '401':
          description: Requires authentication.



  /homes/{id}:
    get:
      tags:
        - home
      security:
        - bearerAuth: []
      summary: Get home
      description: Get a home by its id. Requires authentication.

      parameters:
        - in: path
          name: id
          schema:
            type: integer
          example: 1
          required: true
          description: House identifier

      responses:
        '200':
          description: House with the given id was found and returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Home"
        '401':
          description: Requires authentication.
        '404':
          description: House could not be found.

    patch:
      tags:
        - home
      security:
        - bearerAuth: []
      summary: Update a home
      description: Update a home only if the user is authenticated and is the owner.
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Home identifier
          example: 1

      requestBody:
        description: Home information
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >
                    ** Name of the house **
                    Max length: 60
                    required: false
                  example: Beach house
                address:
                  type: string
                  description: >
                    Max length: 100
                    required: false
                  example: Avocado Street 4
                description:
                  type: string
                  description: >
                    Max length: 500
                    required: false
                  example: 'House with garden!'

      responses:
        '200':
          description: The house was modified
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Home"
        '401':
          description: Requires authentication. User must provide a valid bearer token.
        '403':
          description: Forbidden. The authenticated user is not the owner of the house.
        '404':
          description: Not found. There isn't any house with the given id.

    delete:
      tags:
        - home
      description: Delete a home and all the sensors it had, only if the user is authenticated and is the owner of the house.
      summary: Delete a home

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          schema:
            type: integer
          example: 1
          required: true
          description: House identifier

      responses:
        '204':
          description: No content. Deleted successfully.
        '401':
          description: Requires authentication. User must provide a valid bearer token.
        '403':
          description: Forbidden. The authenticated user is not the owner of the house.
        '404':
          description: Not found. There isn't any house with the given id.

  /homes/{id}/sensors:
    get:
      summary: Get all the sensors in a house
      description: Get all the sensors that are in a house, paginated. Requires authentication. Only allowed to the owner of the house.
      tags:
        - home
        - sensor
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          example: 1
          required: true
          description: House id

      responses:
        '200':
          description: Returns all the sensor that are in a house.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        room:
                          type: string
                          example: Kitchen
                        home_id:
                          type: integer
                          example: 1
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: http://127.0.0.1:8000/homes/1/sensors?page=4
                      last:
                        type: string
                        example: http://127.0.0.1:8000/homes/1/sensors?page=13
                      prev:
                        type: string
                        example: http://127.0.0.1:8000/homes/1/sensors?page=3
                      next:
                        type: string
                        example: http://127.0.0.1:8000/homes/1/sensors?page=5
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 3
                      from:
                        type: integer
                        example: 2
                      last_page:
                        type: integer
                        example: 13
                      links:
                        type: array
                        items:
                          type: object
                          properties:

                            url:
                              type: string
                              example: http://127.0.0.1:8000/homes/1/sensors?page=3
                            label:
                              type: integer
                              example: 3
                            active:
                              type: boolean
                              example: true
                  path:
                    type: string
                    example: http://127.0.0.1:8000/homes/1/sensors
                  per_page:
                    type: integer
                    example: 10
                  to:
                    type: integer
                    example: 4
                  total:
                    type: integer
                    example: 130

        '401':
          description: Requires authentication
        '403':
          description: Forbidden. Only allowed to the owner of the house.
        '404':
          description: The house could not be found.

    post:
      summary: Create a sensor
      description: Creates a sensor for a specific house. Requires authentication. Only allowed to the owner of the house.
      tags:
        - home
        - sensor

      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          example: 1
          required: true
          description: House id

      requestBody:
        description: Sensor information
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                room:
                  type: string
                  example: Kitchen
                  description: >
                    Room where the sensor is placed. 
                    Required: true. 
                    Max length: 100
      responses:
        '201':
          description: A new sensor has been created. Returns the created sensor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sensor"
        '401':
          description: Requires authentication.
        '403':
          description: Forbidden. User is not the owner of the house.
        '404':
          description: House not found.
        '422':
          description: Validation error. Missing values. Too long string...

  /sensors/{id}:
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        example: 1
        required: true
        description: Sensor id

    delete:
      security:
        - bearerAuth: []
      summary: Delete a sensor.
      description: Delete a sensor. Requires authentication. Only allowed to the owner of the sensor.
      tags:
        - sensor

      responses:
        '204':
          description: Sensor was deleted.
        '401':
          description: Requires authentication
        '403':
          description: Forbidden. Only allowed to the owner of the sensor.
        '404':
          description: Sensor could not be found.

  /sensors/{id}/temperatures:
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        example: 1
        required: true
        description: Sensor id

    get:
      tags:
        - temperature
        - sensor
      security:
        - bearerAuth: []
      summary: Get all temperatures measured by a sensor.
      description: Get all temperatures measured by a sensor. Requires authentication. Only allowed to the owner of the sensor.
      responses:
        '200':
          description: Returns all measured temperatures by a sensor. Paginated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        temperature:
                          type: number
                          format: float
                          example: 13.11
                        measured_at:
                          type: string
                          format: date-time
                          example: "2017-07-21T17:32:28Z"
                        sensor_id:
                          type: integer
                          example: 1
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/temperatures?page=4
                      last:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/temperatures?page=13
                      prev:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/temperatures?page=3
                      next:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/temperatures?page=5
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 3
                      from:
                        type: integer
                        example: 2
                      last_page:
                        type: integer
                        example: 13
                      links:
                        type: array
                        items:
                          type: object
                          properties:

                            url:
                              type: string
                              example: http://127.0.0.1:8000/sensors/1/temperatures?page=3
                            label:
                              type: integer
                              example: 3
                            active:
                              type: boolean
                              example: true
                  path:
                    type: string
                    example: http://127.0.0.1:8000/sensors/1/temperatures
                  per_page:
                    type: integer
                    example: 10
                  to:
                    type: integer
                    example: 4
                  total:
                    type: integer
                    example: 130
        '401':
          description: Requires authentication.
        '403':
          description: Forbidden. Only allowed to the owner of the sensor.
        '404':
          description: Sensor not found.

    post:
      tags:
        - temperature
        - sensor
      security:
        - bearerAuth: []
      summary: Create a new temperature
      description: Register a new temperature. Requires authentication. Only allowed to the owner of the sensor.
      requestBody:
        description: Temperature information
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                temperature:
                  type: number
                  format: float
                  description: >
                    Measured temperature. 
                    Required: True
                  example: 23.4
                measured_at:
                  type: string
                  format: date-time
                  description: >
                    When the temperature was measured
                    Required: True
                    Date format
                  example: "2017-07-21T17:32:28Z"
      responses:
        '201':
          description: Temperature stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Temperature"
        '401':
          description: Requires authentication
        '403':
          description: Forbidden. Only allowed to the owner of the sensor.
        '404':
          description: Sensor not found.
        '422':
          description: Validation error. Missing values, incorrect types...

  /temperatures/{id}/predictions:
    post:
      summary: Create a temperature prediction
      description: Store a temperature prediction. Requires authentication. Only allowed to the owner of the sensor with which the temperature was measured.
      tags:
        - prediction
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          example: 1
          required: true
          description: temperature id

      security:
        - bearerAuth: []

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                y_hat:
                  type: number
                  format: float
                  example: 24.2
                y_hat_lower:
                  type: number
                  format: float
                  example: 34.1
                y_hat_upper:
                  type: number
                  format: float
                  example: 11.4
                date:
                  type: string
                  format: date-time
                  example: "2017-07-21T17:32:28Z"
      responses:
        '201':
          description: Prediction stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Prediction"
        '401':
          description: Requires authentication.
        '403':
          description: Forbidden. User is not the owner of the measured temperature.
        '404':
          description: Temperature not found.
        '422':
          description: Validation error. Missing values, incorrect input types...


  /sensors/{id}/predictions:
    parameters:
      - in: path
        name: id
        schema:
          type: integer
        example: 1
        required: true
        description: Sensor id

    get:
      tags:
        - prediction
      summary: Get all the temperature predictions of a sensor
      description: Get all the predictions of a sensor, paginated. Requires authentication. Only allowed to the owner of the sensor.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Returns all predictions. Paginated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        sensor_id:
                          type: integer
                          example: 1
                        temperature_id:
                          type: integer
                          example: 1
                        y_hat:
                          type: number
                          format: float
                          example: 1.1
                        y_hat_lower:
                          type: number
                          format: float
                          example: 3.1
                        y_hat_upper:
                          type: number
                          format: float
                          example: 32.1
                        date:
                          type: string
                          format: date-time
                          example: "2017-07-21T17:32:28Z"
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/predictions?page=4
                      last:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/predictions?page=13
                      prev:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/predictions?page=3
                      next:
                        type: string
                        example: http://127.0.0.1:8000/sensors/1/predictions?page=5
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 3
                      from:
                        type: integer
                        example: 2
                      last_page:
                        type: integer
                        example: 13
                      links:
                        type: array
                        items:
                          type: object
                          properties:

                            url:
                              type: string
                              example: http://127.0.0.1:8000/sensors/1/predictions?page=3
                            label:
                              type: integer
                              example: 3
                            active:
                              type: boolean
                              example: true
                  path:
                    type: string
                    example: http://127.0.0.1:8000/sensors/1/predictions
                  per_page:
                    type: integer
                    example: 10
                  to:
                    type: integer
                    example: 4
                  total:
                    type: integer
                    example: 130

        '401':
          description: Requires authentication.
        '403':
          description: Forbidden. Only allowed to the owner of the sensor.
        '404':
          description: Sensor not found.







components:
  schemas:
    Home:
      type: object
      properties:
        data:
          type: object
          properties:

            id:
              type: integer
              example: 1

            name:
              type: string
              example: Richard's home

            address:
              type: string
              example: New-lands Rise

            description:
              type: string
              example: House with pool!

            user_id:
              type: integer
              example: 1


    Auth:
      type: object
      properties:

        data:
          type: object
          properties:

            token:
              type: string
              example: "1|Bls37PLszsyHnhheXAElRyxOUnfZGPtbO9xRSVNU"


    User:
      type: object
      properties:
        data:
          type: object
          properties:

            id:
              type: integer
              example: 1

            username:
              type: string
              example: Robert

    Sensor:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 1
            room:
              type: string
              example: Kitchen
            home_id:
              type: integer
              example: 1


    Temperature:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 1
            temperature:
              type: number
              format: float
              example: 25.2

            measured_at:
              type: string
              format: date-time
              example: "2017-07-21T17:32:28Z"
            sensor_id:
              type: integer
              example: 1

    Prediction:
      type: object
      properties:
        data:
          type: object
          properties:
            sensor_id:
              type: integer
              example: 1
            temperature_id:
              type: integer
              example: 1
            y_hat:
              type: number
              format: float
              example: 21.1
            y_hat_lower:
              type: number
              format: float
              example: 23.2
            y_hat_upper:
              type: number
              format: float
              example: 11.2
            date:
              type: string
              format: date-time
              example: "2017-07-21T17:32:28Z"



  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # optional, for documentation purposes only
      description: >-
        Enter the token that is given when a user logs in.