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