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.
202 lines
7.7 KiB
202 lines
7.7 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: "0.1.0 - Alpha" |
|
title: Return to Ritherdon Project A.P.I. |
|
consumes: |
|
- application/json |
|
produces: |
|
- application/json |
|
|
|
basePath: /api |
|
|
|
paths: |
|
/readings/add/{light_meter}: |
|
post: |
|
operationId: api.post_a_reading |
|
tags: |
|
- Store 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.880010 |
|
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. |
|
responses: |
|
201: |
|
description: >- |
|
The reading was successfully added to the database. |
|
|
|
/readings/latest/{light_meter}: |
|
get: |
|
operationId: api.get_latest |
|
tags: |
|
- Request 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 JASON |
|
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). |
|
|
|
/readings/all/{light_meter}: |
|
get: |
|
operationId: api.get_all_readings |
|
tags: |
|
- Request Readings |
|
summary: >- |
|
Returns every reading taken by the specified light meter. |
|
description: >- |
|
Use this U.R.L. to retrieve the 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). |
|
|
|
/readings/all: |
|
get: |
|
operationId: api.get_all_readings_for_every_meter |
|
tags: |
|
- Request 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
|
|
|