You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
415 lines
16 KiB
415 lines
16 KiB
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 - Alpha" |
|
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 changed 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
|
|
|