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.
238 lines
8.6 KiB
238 lines
8.6 KiB
4 years ago
|
swagger: "2.0"
|
||
|
info:
|
||
|
description: >-
|
||
|
This A.P.I. is part of the, at time of writing, unnamed project by
|
||
|
Nicola Ellis. The project's code-name is Roaming Light A.P.I.
|
||
|
version: "0.0.1 - 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_reading
|
||
|
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
|
||
|
|
||
|
# This is the in-mem. database URL.
|
||
|
/readings/late/{light_meter}:
|
||
|
get:
|
||
|
operationId: api.get_latest
|
||
|
tags:
|
||
|
- Request Readings
|
||
|
summary: >-
|
||
|
Returns latest from in-mem database.
|
||
|
description: >-
|
||
|
latest in-mem db reading
|
||
|
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: >-
|
||
|
In-mem db latest value
|
||
|
schema:
|
||
|
type: object
|
||
|
properties:
|
||
|
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).
|