Skip to content

Commit 63b3de8

Browse files
jondaytonjondayton
committed
update conformity to OpenAPI spec
1 parent 98b37f1 commit 63b3de8

2 files changed

Lines changed: 136 additions & 72 deletions

File tree

‎versions/master/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
1313

1414
There are specific concepts that all participants in this open API must support in order to make interaction possible. Each of these concepts should be driven by factory configurations or by on-site configurations made by the customer or a professional integrator.
1515

16-
Compliance with the Open-Agtech API requires adherence to the OpenAPI Specification (currently [3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md)). In addition, there are several principles that account for the needs of our industry.
16+
Compliance with the Open-Agtech API requires adherence to the OpenAPI Specification (currently [3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md)).
17+
18+
# OpenAPI Specification
19+
20+
For convenience, we have included some of the more important and relevant concepts of the OpenAPI spec. While the complete spec is not located here, these concepts will provide a foundation for building a compliant API.
21+
22+
### Open AgTech API Document
23+
24+
The Open AgTech API Document describes the structure of a compliant API. Documents MUST be in YAML or JSON format and SHOULD be accessible to consumers of the API. You can read more about the structure of the document at the [Open API Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#document-structure), or see examples (**TODO: EXAMPLES**)
25+
26+
In addition, there are several principles that account for the needs of our industry.
1727

1828
# URL construction
1929

‎versions/master/lights.md‎

Lines changed: 125 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,127 @@
1-
# Purpose
2-
3-
This specification is intended to define a standardized way of communicating with lighting systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices.
4-
5-
**NOTE:** need to add API to query last-known update...identify what was done and when (and by whom?)
6-
7-
# Scope
8-
9-
The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below.
10-
11-
# Definitions
12-
13-
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
14-
15-
# Endpoints
16-
## Sensors
17-
### Talking to one sensor
18-
**Retrieving ID information**
19-
```
20-
GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info
21-
```
22-
Returns [Info](general.md#info-data)
23-
24-
**Sending ID information**
25-
```
26-
POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info
27-
```
28-
Sends [Info](general.md#info-data)
29-
30-
**Retrieving version information**
31-
```
32-
GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/version
33-
```
34-
Returns [Version](general.md#version-data)
35-
36-
**Retrieving location information**
37-
```
38-
GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location
39-
```
40-
Returns [Location](general.md#location-data)
41-
42-
**Sending location information**
43-
```
44-
POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location
45-
```
46-
Sends [Location](general.md#location-data)
1+
## Example Document Snippets
2+
3+
```yaml
4+
/sensors:
5+
get:
6+
description: Returns all sensors from the system that the user has access to
7+
responses:
8+
'200':
9+
description: A list of sensors.
10+
content:
11+
application/json:
12+
schema:
13+
type: array
14+
items:
15+
$ref: '#/components/schemas/Sensor'
16+
/sensors/{sensorId}:
17+
get:
18+
summary: Info for a specific sensor
19+
operationId: showSensorById
20+
tags:
21+
- sensors
22+
parameters:
23+
- name: sensorId
24+
in: path
25+
required: true
26+
description: The id of the sensor to retrieve
27+
schema:
28+
type: string
29+
responses:
30+
'200':
31+
description: Expected response to a valid request
32+
content:
33+
application/json:
34+
schema:
35+
$ref: "#/components/schemas/Sensors"
36+
default:
37+
description: unexpected error
38+
content:
39+
application/json:
40+
schema:
41+
$ref: "#/components/schemas/Error"
42+
43+
/sensors/{sensorId}/measurements:
44+
get:
45+
description: Returns spectrum measurements from a specific sensor
46+
parameters:
47+
- name: format
48+
in: query
49+
required: false
50+
description: PPF or PPFD
51+
schema:
52+
type: string
53+
responses:
54+
'200':
55+
description: A list of measurements
56+
content:
57+
application/json:
58+
schema:
59+
type: array
60+
items:
61+
$ref: '#/components/schemas/SpectrumMeasurement'
62+
63+
```
64+
65+
### Example Schema
66+
67+
Sensor
68+
69+
```yaml
70+
type: object
71+
required:
72+
- id
73+
properties:
74+
name:
75+
type: string
76+
info:
77+
type: string
78+
version:
79+
type: string
80+
location:
81+
***TODO: LOCATION FORMAT*** general.md#location-data
82+
age:
83+
type: integer
84+
format: int32
85+
minimum: 0
86+
```
87+
88+
Measurement
89+
90+
```yaml
91+
type: object
92+
required:
93+
- id
94+
properties:
95+
id:
96+
description: Unique id of the device
97+
type: string
98+
timestamp:
99+
description: UTC timestamp of the measurement
100+
type: string
101+
red:
102+
description: Level of red spectrum light
103+
type: string
104+
blue:
105+
description: Level of blue spectrum light
106+
type: string
107+
green:
108+
description: Level of green spectrum light
109+
type: string
110+
uv:
111+
description: Level of ultraviolet light
112+
type: string
113+
infrared:
114+
description: Level of infrared light
115+
type: string
116+
par:
117+
description: Level of absorbable light
118+
type: string
119+
light:
120+
description: Level of all spectrums of light
121+
type: string
122+
```
123+
124+
## Example requests
47125
48126
**Retrieving spectrum measurements as PPF**
49127
```
@@ -143,31 +221,7 @@ GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppfd
143221
```
144222
Returns an array of [Light PPFD](lights.md#light-ppfd)
145223

146-
### Light PPF
147-
| Name | Description | Unit |
148-
| --------- | -------------------------------- | -------- |
149-
| id | Unique id of the device | uid |
150-
| timestamp | UTC timestamp of the measurement | datetime |
151-
| red | Level of red spectrum light | PPF |
152-
| blue | Level of blue spectrum light | PPF |
153-
| green | Level of green spectrum light | PPF |
154-
| uv | Level of ultraviolet light | PPF |
155-
| infrared | Level of infrared light | PPF |
156-
| par | Level of absorbable light | PPF |
157-
| light | Level of all spectrums of light | PPF |
158-
159-
### Light PPFD
160-
| Name | Description | Unit |
161-
| --------- | -------------------------------- | -------- |
162-
| id | Unique id of the device | uid |
163-
| timestamp | UTC timestamp of the measurement | datetime |
164-
| red | Level of red spectrum light | PPFD |
165-
| blue | Level of blue spectrum light | PPFD |
166-
| green | Level of green spectrum light | PPFD |
167-
| uv | Level of ultraviolet light | PPFD |
168-
| infrared | Level of infrared light | PPFD |
169-
| par | Level of absorbable light | PPFD |
170-
| light | Level of all spectrums of light | PPFD |
224+
171225

172226
## Fixtures
173227
### Talking to one fixture

0 commit comments

Comments
 (0)