midpoint/app/swagger.yml

swagger: "2.0"
info:
  description: >-
    The 'Return to Ritherdon' project, by Nicola Ellis, is a two year art residency at Ritherdon & Co Ltd, a manufacturer of metal enclosures based in Darwen, Lancashire U.K. This website is part of the many outcomes produced throughout the duration of project.
  version: "1.0.0 - Beta"
  title: Return to Ritherdon Project A.P.I.
consumes:
  - application/json
produces:
  - application/json

basePath: /api

paths:
# Light-Meter A.P.I. Calls
# ====================================================================
  /readings/add/{light_meter}:
    post:
      operationId: api.post_a_reading
      tags:
        - Log Light-Meter Readings
      summary: >-
        Posts a reading from one of the project's light meters and store
        it in the database.
      description: >-
        Use this U.R.L. to post a new reading from of the light meters
        used in the project. At the time of writing, there are three
        light meters taking readings in the Ritherdon factory.
        It is important to note which light meter is posting the
        reading. Each light meter has its own table in the database
        and it will corrupt the data integrity if you post a reading
        from a meter into the wrong table. At the time of writing,
        there are three meters taking light reading and posting them
        to here.
      parameters:
        - name: light_meter
          in: path
          description: >-
            The Id. of the light meter which has taken the reading. At
            the time of writing, it should be a number between 1-3.
          type: integer
          required: True
        - name: the_reading
          in: body
          description: >-
            The data object which represents a single light reading
            from light meter 1. It conveys the time the reading was
            taken and the light value it recorded. Remember, each light
            has their own table in the database so make sure you do not
            post the light meter reading to the wrong URL. It will
            corrupt the data integrity.
          required: True
          schema:
            type: object
            properties:
              time:
                type: string
                format: date-time
                example: 2019-10-19 17:04:57
                description: >-
                  The date and time the reading was taken. Make sure
                  you use the UTC time format. This is because the
                  A.P.I. has made a design decision to standardise on
                  it.
              reading:
                type: integer
                example: 23
                description: >-
                  This represents the amount of light the light meter
                  recorded. This is the most important piece of data
                  you will post in this data-object.
              token:
                type: string
                example: it-is-not-password-if-you-are-wondering
                description: >-
                  This is basically a token to check the info. sent to
                  the server is from a valid machine.
      responses:
        201:
          description: >-
            The reading was successfully added to the database.
        400:
          description: >-
            The data sent to the sever was invalid or incorrectly
            formatted. The most likely reasons are invalid light-meter
            Id. specified and incorrect datetime format used.

  /readings/latest/{light_meter}:
    get:
      operationId: api.get_latest
      tags:
        - Request Light-Meter Readings
      summary: >-
        Returns the latest reading from the specified light meter.
      description: >-
        Use this U.R.L. to retrieve the latest reading from the
        light meter you specified (in the U.R.L.). At the time of
        writing, the project has only three light meters and are
        labelled 1-3.
      parameters:
        - name: light_meter
          in: path
          description: >-
            This is the Id. of the light meter which you are retrieving
            the reading for. The Id. consists of a number between 1-3
            at the time of writing.
          type: integer
          required: True
      responses:
        200:
          description: >-
            If the server can successfully retrieve the latest reading
            for the specified light meter, you should receive a JSON
            object like the one below. It should include the Id. of
            the light meter it was taken with, the time the reading
            was taken and the reading itself.
          schema:
            type: object
            properties:
                id:
                  type: integer
                  example: 2
                  description: >-
                    This is the Id. of the light meter which took the
                    reading. It should be between 1-3 at the time of
                    writing.
                time:
                  type: string
                  example: 2019-10-19 17:04:57
                  description: >-
                    The time and date the reading was taken. The A.P.I.
                    has standardised on the U.T.C. format.
                reading:
                  type: integer
                  example: 34
                  description: >-
                    This is the actual reading taken from the specified
                    light meter, at the time specified in this response
                    body (I.E. JSON object).
        400:
          description: >-
            The light-meter Id. specified in invalid.

  /readings/all/{light_meter}:
    get:
      operationId: api.get_all_readings
      tags:
        - Request Light-Meter Readings
      summary: >-
        Returns every reading taken by the specified light meter.
      description: >-
        Use this U.R.L. to retrieve all the reading from the
        light meter you specified (in the U.R.L.). At the time of
        writing, the project has only three light meters and are
        labelled 1-3.
      parameters:
        - name: light_meter
          in: path
          description: >-
            This is the Id. of the light meter which you are retrieving
            the readings for. The Id. consists of a number between 1-3
            at the time of writing.
          type: integer
          required: True
      responses:
        200:
          description: >-
            If the server can successfully retrieve all the readings
            for the specified light meter, you should receive an array
            of JSON objects like the one below. It should include the
            database Id. of the reading, the time the reading was
            taken and the reading itself.
          schema:
            type: object
            properties:
                id:
                  type: integer
                  example: 2
                  description: >-
                    This is the database Id. of the reading.
                time:
                  type: string
                  example: 2019-10-19 17:04:57
                  description: >-
                    This is the time and date the reading was taken.
                    The A.P.I. has standardised on the U.T.C. format.
                reading:
                  type: integer
                  example: 34
                  description: >-
                    This is the actual reading taken from the specified
                    light meter, at the time specified in this response
                    body (I.E. JSON object).
        400:
          description: >-
            The light-meter Id. specified in invalid.

  /readings/all:
    get:
      operationId: api.get_all_readings_for_every_meter
      tags:
        - Request Light-Meter Readings
      summary: >-
        Returns every reading taken by every light meter in the
        project.
      description: >-
        Use this U.R.L. to retrieve all the readings from every light
        meter in the project. There is no example of the data returned
        because I can't seem to replicate it as a YAML schema which
        is understood by Swagger. Because of this, it is registered as
        a free-form object. To see what the data looks like when it is
        returned, I recommend you use the "Try it out!" button to see a
        working example.
      responses:
        200:
          description: >-
            All the readings were successfully retrieved from the
            database and delivered.
          schema:
            type: object
            additionalProperties: True

# Device A.P.I. Calls
# ====================================================================
  /status/update/{device}:
    post:
      operationId: api.post_a_status_change
      tags:
        - Log Device Status Change
      summary: >-
        Logs a change in the status of the specified device.
      description: >-
        This is mostly to check if the devices included in this project
        are turned on, off or an error has occured and they are
        unreachable/crashed.
      parameters:
        - name: device
          in: path
          description: >-
            The Id. of the device with the change in status. 1, 2 and 3
            refer to the light-meters in Ritherdon and 4, 5 and 6
            refer to the relays in the gallery. The pairing of each
            meter and relay is as follows: 1->4, 2->5 and 3->6.
          type: integer
          required: True
        - name: the_status_change
          in: body
          description: >-
            The status change and the time the change occurred.
          required: True
          schema:
            type: object
            properties:
              time:
                type: string
                format: date-time
                example: 2019-10-19 17:04:57
                description: >-
                  The date and time the change in status occurred. Make
                  sure to use the U.T.C. time format. This is because
                  the A.P.I. has made a design decision to standardise
                  on it.
              status:
                type: string
                example: "on"
                description: >-
                  The current status of the device you would like to log.
                  The two status types are "on" and "off".
              token:
                type: string
                example: it-is-not-password-if-you-are-wondering
                description: >-
                  This is basically a token to check the info. sent to
                  the server is from a valid machine.
      responses:
        201:
          description: >-
            The status update was successfully added to the database.
        400:
          description: >-
            The data sent to the sever was invalid or incorrectly
            formatted. The most likely reasons are invalid device Id.
            specified and incorrect datetime format used.

  /status/latest/{device}:
    get:
      operationId: api.get_latest_device_status
      tags:
        - Request Device Status
      summary: >-
        Returns the current status of the specified device.
      description: >-
        Use this U.R.L. to retrieve the current status of the device
        you specified (in the U.R.L.). At the time of writing, the
        project has six devices in total which are split equally
        between Ritherdon and the gallery. Devices 1 to 3 (light-meters)
        refer to the devices in Ritherdon and 4 to 6 (relays) are in
        the gallery. Each light-meter and relay should pair up in the
        following ways: 1->4, 2->5 and 3->6.
      parameters:
        - name: device
          in: path
          description: >-
            This is the Id. of the device which you are retrieving the
            current status for. The Id. should consist of a number
            between 1 and 6, at the time of writing.
          type: integer
          required: True
      responses:
        200:
          description: >-
            If the server can successfully retrieve the current status
            for the specified device, you should receive a JSON object
            like the one below. It should include the Id. of the
            device, the current status and the time it was logged.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 2
                description: >-
                  The is the Id. of the device.
              time:
                type: string
                example: 2019-10-19 17:04:57
                description: >-
                  The time the status change was logged in the
                  database. The A.P.I. has standardised on the
                  U.T.C. format.
              status:
                type: string
                example: on
                description: The current status of the device.
        400:
          description: >-
            The device Id. specified in invalid.

  /status/all/{device}:
    get:
      operationId: api.get_all_status_log
      tags:
        - Request Device Status
      summary: >-
        Returns every status change logged by the specified device.
      description: >-
        Use this U.R.L. to retrieve every change in the specified
        devices state. At the time of writing, the project has six
        devices and are labelled 1 to 6. Devices (light-meters) 1 to 3
        are located in the Ritherdon factory and 4 to 6 (relays) in the
        gallery. The light-meters and relays are paired like so, 1->4,
        2->5 and 3->6.
      parameters:
        - name: device
          in: path
          description: >-
            The Id. of the device you are retrieving the status change
            log for. The Id. should be a number between 1 and 6.
          type: integer
          required: True
      responses:
        200:
          description: >-
            If the server can successfully retrieve all the status logs
            for the specified device, you should receive an array of
            JSON objects like the one in the example below. It should
            include the database Id. of the logged status change, the
            time the status change was logged and the status itself.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 3
                description: >-
                  This is the database Id. of the logged status change.
              time:
                type: string
                example: 2019-10-19 17:23:23
                description: >-
                  The time and date the status change was logged. The
                  A.P.I. has standardised on the U.T.C. format.
              status:
                type: string
                example: off
                description: >-
                  The status of the device after the change occurred.
        400:
          description: >-
            The device Id. specified in invalid.

  /status/all:
    get:
      operationId: api.get_all_status_logs_for_every_device
      tags:
        - Request Device Status
      summary: >-
        Returns every logged status change of every device in the
        project.
      description: >-
        Use this U.R.L. to retrieve every logged status change of every
        device used in this project. There is no example of the data
        returned because I can't seem to replicate it as a YAML schema
        which is understood by Swagger. Because of this. the return
        type is registered as a free-form object. To see what the data
        looks like when it is returned, I recommend you use the "Try it
        out!" button to see a working example.
      responses:
        200:
          description: >-
            All the logged status changes of every device were
            successfully retrieved from the database and delivered.
          schema:
            type: object
            additionalProperties: True
            
  /status/latest:
    get:
      operationId: api.get_current_status_for_all_devices
      tags:
        - Request Device Status
      summary: >-
        Returns the last recorded status change of every device in the
        database.
      description: >-
        Use this U.R.L. to retrieve the last recorded status change of
        every device used in this project. There is no example of the
        data returned because I can't seem to replicate it as a YAML
        schema which is understood by Swagger. Because of this. the
        return type is registered as a free-form object. To see what
        the data looks like when it is returned, I recommend you use
        the "Try it out!" button to see a working example.
      responses:
        200:
          description: >-
            The last recorded status change of every device in this
            project was retrieved successfully.
          schema:
            type: object
            additionalProperties: True