From 98b37f1e12ecc6bcdb839204ad925ed2c4c6f5c3 Mon Sep 17 00:00:00 2001 From: jondayton Date: Thu, 5 Jul 2018 13:25:30 -0400 Subject: [PATCH 1/4] move examples into versioning --- {examples => versions/master/examples}/README.md | 0 {examples => versions/master/examples}/air-examples.md | 0 {examples => versions/master/examples}/light-examples.md | 0 {examples => versions/master/examples}/water-examples.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename {examples => versions/master/examples}/README.md (100%) rename {examples => versions/master/examples}/air-examples.md (100%) rename {examples => versions/master/examples}/light-examples.md (100%) rename {examples => versions/master/examples}/water-examples.md (100%) diff --git a/examples/README.md b/versions/master/examples/README.md similarity index 100% rename from examples/README.md rename to versions/master/examples/README.md diff --git a/examples/air-examples.md b/versions/master/examples/air-examples.md similarity index 100% rename from examples/air-examples.md rename to versions/master/examples/air-examples.md diff --git a/examples/light-examples.md b/versions/master/examples/light-examples.md similarity index 100% rename from examples/light-examples.md rename to versions/master/examples/light-examples.md diff --git a/examples/water-examples.md b/versions/master/examples/water-examples.md similarity index 100% rename from examples/water-examples.md rename to versions/master/examples/water-examples.md From 63b3de831dacb645c81080857fe1e16cf1f9cee2 Mon Sep 17 00:00:00 2001 From: jondayton Date: Thu, 21 Jun 2018 13:55:12 -0400 Subject: [PATCH 2/4] update conformity to OpenAPI spec --- versions/master/README.md | 12 ++- versions/master/lights.md | 196 ++++++++++++++++++++++++-------------- 2 files changed, 136 insertions(+), 72 deletions(-) diff --git a/versions/master/README.md b/versions/master/README.md index fe6bbc3..e3f52e5 100644 --- a/versions/master/README.md +++ b/versions/master/README.md @@ -13,7 +13,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S 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. -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. +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)). + +# OpenAPI Specification + +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. + +### Open AgTech API Document + +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**) + +In addition, there are several principles that account for the needs of our industry. # URL construction diff --git a/versions/master/lights.md b/versions/master/lights.md index 5f94ea8..2053797 100644 --- a/versions/master/lights.md +++ b/versions/master/lights.md @@ -1,49 +1,127 @@ -# Purpose - -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. - -**NOTE:** need to add API to query last-known update...identify what was done and when (and by whom?) - -# Scope - -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. - -# Definitions - -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. - -# Endpoints -## Sensors -### Talking to one sensor -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info -``` -Returns [Info](general.md#info-data) - -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info -``` -Sends [Info](general.md#info-data) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/version -``` -Returns [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location -``` -Returns [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location -``` -Sends [Location](general.md#location-data) +## Example Document Snippets + +```yaml +/sensors: + get: + description: Returns all sensors from the system that the user has access to + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' +/sensors/{sensorId}: + get: + summary: Info for a specific sensor + operationId: showSensorById + tags: + - sensors + parameters: + - name: sensorId + in: path + required: true + description: The id of the sensor to retrieve + schema: + type: string + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + $ref: "#/components/schemas/Sensors" + default: + description: unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + +/sensors/{sensorId}/measurements: + get: + description: Returns spectrum measurements from a specific sensor + parameters: + - name: format + in: query + required: false + description: PPF or PPFD + schema: + type: string + responses: + '200': + description: A list of measurements + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SpectrumMeasurement' + +``` + +### Example Schema + +Sensor + +```yaml +type: object +required: +- id +properties: + name: + type: string + info: + type: string + version: + type: string + location: + ***TODO: LOCATION FORMAT*** general.md#location-data + age: + type: integer + format: int32 + minimum: 0 +``` + +Measurement + +```yaml +type: object +required: +- id +properties: + id: + description: Unique id of the device + type: string + timestamp: + description: UTC timestamp of the measurement + type: string + red: + description: Level of red spectrum light + type: string + blue: + description: Level of blue spectrum light + type: string + green: + description: Level of green spectrum light + type: string + uv: + description: Level of ultraviolet light + type: string + infrared: + description: Level of infrared light + type: string + par: + description: Level of absorbable light + type: string + light: + description: Level of all spectrums of light + type: string +``` + +## Example requests **Retrieving spectrum measurements as PPF** ``` @@ -143,31 +221,7 @@ GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppfd ``` Returns an array of [Light PPFD](lights.md#light-ppfd) -### Light PPF -| Name | Description | Unit | -| --------- | -------------------------------- | -------- | -| id | Unique id of the device | uid | -| timestamp | UTC timestamp of the measurement | datetime | -| red | Level of red spectrum light | PPF | -| blue | Level of blue spectrum light | PPF | -| green | Level of green spectrum light | PPF | -| uv | Level of ultraviolet light | PPF | -| infrared | Level of infrared light | PPF | -| par | Level of absorbable light | PPF | -| light | Level of all spectrums of light | PPF | - -### Light PPFD -| Name | Description | Unit | -| --------- | -------------------------------- | -------- | -| id | Unique id of the device | uid | -| timestamp | UTC timestamp of the measurement | datetime | -| red | Level of red spectrum light | PPFD | -| blue | Level of blue spectrum light | PPFD | -| green | Level of green spectrum light | PPFD | -| uv | Level of ultraviolet light | PPFD | -| infrared | Level of infrared light | PPFD | -| par | Level of absorbable light | PPFD | -| light | Level of all spectrums of light | PPFD | + ## Fixtures ### Talking to one fixture From 4d1729a3473a5472fc625552b6f03fac681b526b Mon Sep 17 00:00:00 2001 From: jondayton Date: Thu, 28 Jun 2018 13:08:01 -0400 Subject: [PATCH 3/4] finish conversion of light examples to be openapi compliant --- versions/master/lights.md | 407 +++++++++++++++----------------------- 1 file changed, 159 insertions(+), 248 deletions(-) diff --git a/versions/master/lights.md b/versions/master/lights.md index 2053797..c777375 100644 --- a/versions/master/lights.md +++ b/versions/master/lights.md @@ -1,7 +1,7 @@ ## Example Document Snippets ```yaml -/sensors: +/light_sensors: get: description: Returns all sensors from the system that the user has access to responses: @@ -13,7 +13,7 @@ type: array items: $ref: '#/components/schemas/Sensor' -/sensors/{sensorId}: +/light_sensors/{sensorId}: get: summary: Info for a specific sensor operationId: showSensorById @@ -32,7 +32,9 @@ content: application/json: schema: - $ref: "#/components/schemas/Sensors" + type: array + items: + $ref: "#/components/schemas/Sensors" default: description: unexpected error content: @@ -40,14 +42,14 @@ schema: $ref: "#/components/schemas/Error" -/sensors/{sensorId}/measurements: +/light_sensors/{sensorId}/measurements: get: description: Returns spectrum measurements from a specific sensor parameters: - - name: format + - name: type in: query required: false - description: PPF or PPFD + description: ppf or ppfd, defaults to ppfd schema: type: string responses: @@ -60,11 +62,86 @@ items: $ref: '#/components/schemas/SpectrumMeasurement' +/zone/{zoneId}/sensors: + get: + description: Returns all sensors from a zone + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' + +light_sensors: + get: + description: Returns all sensors from a zone + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' + +light_fixtures: + get: + description: Returns all fixtures that a user has access to + responses: + '200': + description: A list of fixtures. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Fixture' + +/light_fixtures/{fixtureId}: + get: + summary: Info for a specific fixture + operationId: showFixtureById + tags: + - fixtures + parameters: + - name: fixtureId + in: path + required: true + description: The id of the fixture to retrieve + schema: + type: string + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Fixture" + + +/light_fixtures/{fixtureId}/light_channels: + get: + description: Returns all channels from a fixture + responses: + '200': + description: A list of channels. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Channel' ``` -### Example Schema +## Example Schema -Sensor +### Sensor ```yaml type: object @@ -79,13 +156,15 @@ properties: type: string location: ***TODO: LOCATION FORMAT*** general.md#location-data + info: + ***TODO: INFO FORMAT*** general.md#info-data age: type: integer format: int32 minimum: 0 ``` -Measurement +### Measurement ```yaml type: object @@ -121,289 +200,121 @@ properties: type: string ``` -## Example requests - -**Retrieving spectrum measurements as PPF** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppf -``` -Returns [Light PPF](lights.md#light-ppf) - -**Retrieving spectrum measurements as PPFD** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppfd -``` -Returns [Light PPFD](lights.md#light-ppfd) +### Fixture -### Talking to all sensors -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/info -``` -Returns an array of [Info](general.md#info-data) - -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/info -``` -Sends an array of [Info](general.md#info-data) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/version -``` -Returns an array of [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/location -``` -Returns an array of [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/location -``` -Sends an array of [Location](general.md#location-data) - -**Retrieving spectrum measurements as PPF** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/ppf -``` -Returns an array of [Light PPF](lights.md#light-ppf) - -**Retrieving spectrum measurements as PPFD** -``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/ppfd -``` -Returns an array of [Light PPFD](lights.md#light-ppfd) - -### Talking to all sensors in a zone -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info -``` -Returns an array of [Info](general.md#info-data) - -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info -``` -Sends an array of [Info](general.md#info-data) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/version -``` -Returns an array of [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location -``` -Returns an array of [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location -``` -Sends an array of [Location](general.md#location-data) - -**Retrieving spectrum measurements as PPF** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppf -``` -Returns an array of [Light PPF](lights.md#light-ppf) - -**Retrieving spectrum measurements as PPFD** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppfd -``` -Returns an array of [Light PPFD](lights.md#light-ppfd) - - - -## Fixtures -### Talking to one fixture -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info -``` -Returns [Info](general.md#info-data) - -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info -``` -Sends [Info](general.md#info-data) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/version -``` -Returns [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location -``` -Returns [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location -``` -Sends [Location](general.md#location-data) - -**Retrieving configuration information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config +```yaml +type: object +required: +- id +- status +properties: + id: + description: Unique id of the fixture + type: string + name: + type: string + status: + description: The active state of the light ('on' or 'off') + type: string ``` -Returns [Fixture Configuration](lights.md#fixture-configuration) -**Sending configuration information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config +```yaml +type: object +required: +- id +properties: + name: + type: string + status: + description: The active state of the light ('on' or 'off') + type: string ``` -Sends [Fixture Configuration](lights.md#fixture-configuration) -**Retrieving power state information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power -``` -Returns [Fixture Power](lights.md#fixture-power) +### Channel -**Sending power state information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power +```yaml +type: object +required: +- id +properties: + id: + description: Unique id of the channel + lo-color: + description: Lower boundary of the frequency range for a color channel + format: ***TODO FORMAT nm*** + hi-color: + description: Upper boundary of the frequency range for a color channel + format: ***TODO FORMAT nm*** + cct: + description: Color temperature for a white channel + format: ***TODO FORMAT K (Kelvin)*** + intensity: + description: Light intensity + format: ***TODO FORMAT %*** ``` -Sends [Fixture Power](lights.md#fixture-power) -### Talking to all fixtures -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/info -``` -Returns an array of [Info](general.md#info-data) -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/info -``` -Sends an array of [Info](general.md#info-data) +## Example requests -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/version -``` -Returns an array of [Version](general.md#version-data) +### Sensors -**Retrieving location information** +**Retrieving sensor information** ``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/location +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid] ``` -Returns an array of [Location](general.md#location-data) -**Sending location information** +**Updating sensor information** ``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/location +PUT http://[domain:port]/agroapi/[version]/light_sensors/[sensorid] ``` -Sends an array of [Location](general.md#location-data) -**Retrieving configuration information** +**Retrieving spectrum measurements as PPF** ``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/config +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid]/measurements?type=ppf ``` -Returns an array of [Fixture Configuration](lights.md#fixture-configuration) -**Sending configuration information** +**Retrieving spectrum measurements as PPFD** ``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/config +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid]/measurements?type=ppf ``` -Sends an array of [Fixture Configuration](lights.md#fixture-configuration) -**Retrieving power state information** +**Retrieving information for all sensors** ``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/power +GET http://[domain:port]/agroapi/[version]/light_sensors ``` -Returns an array of [Fixture Power](lights.md#fixture-power) -**Sending power state information** +**Retrieving information for all sensors in a zone** ``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/power +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/light_sensors ``` -Sends an array of [Fixture Power](lights.md#fixture-power) -### Talking to all fixtures in a zone -**Retrieving ID information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info -``` -Returns an array of [Info](general.md#info-data) -**Sending ID information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info -``` -Sends an array of [Info](general.md#info-data) +### Fixtures -**Retrieving version information** +**Retrieving information for all fixtures** ``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixture/[fixtureid]/version +GET http://[domain:port]/agroapi/[version]/light_fixtures ``` -Returns an array of [Version](general.md#version-data) -**Retrieving location information** +**Retrieving information for a fixture** ``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location +GET http://[domain:port]/agroapi/[version]/light_fixtures/[fixtureid] ``` -Returns an array of [Location](general.md#location-data) -**Sending location information** +**Updating information for a fixture** ``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location +PUT http://[domain:port]/agroapi/[version]/light_fixtures/[fixtureid] ``` -Sends an array of [Location](general.md#location-data) -**Retrieving configuration information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config -``` -Returns an array of [Fixture Configuration](lights.md#fixture-configuration) -**Sending configuration information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config -``` -Sends an array of [Fixture Configuration](lights.md#fixture-configuration) +### Channels -**Retrieving power state information** +**Retrieving channel configurations for a fixture** ``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power +GET http://[domain:port]/agroapi/[version]/light_fixtures/[fixture_id]/light_channels ``` -Returns an array of [Fixture Power](lghts.md#fixture-power) -**Sending power state information** +**Updating channel configuration** ``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power +PUT http://[domain:port]/agroapi/[version]/light_channels/[channel_id] ``` -Sends an array of [Fixture Power](lghts.md#fixture-power) - -### Fixture Configuration -| Name | Description | Unit | -| -------- | ------------------------------- | ----- | -| id | Unique id of the fixture | uid | -| channels | array of channel configurations | [Channel Configuration](lights.md#channel-configuration) | -### Channel Configuration -| Name | Description | Unit | -| ----------- | --------------------------------------------------------- | ---------- | -| id | Unique id of the channel | uid | -| lo-color | Lower boundary of the frequency range for a color channel | nm | -| hi-color | Upper boundary of the frequency range for a color channel | nm | -| cct | Color temperature for a white channel | K (Kelvin) | -| intensity | Light intensity | % | -### Fixture Power -| Name | Description | Unit | -| ------ | ------------------------------ | ------------- | -| id | Unique id of the fixture | uid | -| status | The active state of the lights | "on" or "off" | From e5d93de40416afe7329fb139a4beff00a7e280ed Mon Sep 17 00:00:00 2001 From: jondayton Date: Thu, 5 Jul 2018 13:43:08 -0400 Subject: [PATCH 4/4] moved light examples into documents --- .../master/examples/documents/lights.yaml | 247 +++++++++++++++++ versions/master/lights.md | 256 ------------------ 2 files changed, 247 insertions(+), 256 deletions(-) create mode 100644 versions/master/examples/documents/lights.yaml diff --git a/versions/master/examples/documents/lights.yaml b/versions/master/examples/documents/lights.yaml new file mode 100644 index 0000000..96de438 --- /dev/null +++ b/versions/master/examples/documents/lights.yaml @@ -0,0 +1,247 @@ +openapi: "3.0.0" +info: + version: 1.0.0 + title: FarmCo Lights + license: + name: MIT +servers: + - url: http://farmco.example.com/agroapi/v1 +paths: + /light_sensors: + get: + description: Returns all sensors from the system that the user has access to + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' + /light_sensors/{sensorId}: + get: + summary: Info for a specific sensor + operationId: showSensorById + tags: + - sensors + parameters: + - name: sensorId + in: path + required: true + description: The id of the sensor to retrieve + schema: + type: string + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Sensors" + default: + description: unexpected error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + + /light_sensors/{sensorId}/measurements: + get: + description: Returns spectrum measurements from a specific sensor + parameters: + - name: type + in: query + required: false + description: ppf or ppfd, defaults to ppfd + schema: + type: string + responses: + '200': + description: A list of measurements + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SpectrumMeasurement' + + /zone/{zoneId}/sensors: + get: + description: Returns all sensors from a zone + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' + + /light_sensors: + get: + description: Returns all sensors from a zone + responses: + '200': + description: A list of sensors. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Sensor' + + /light_fixtures: + get: + description: Returns all fixtures that a user has access to + responses: + '200': + description: A list of fixtures. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Fixture' + + /light_fixtures/{fixtureId}: + get: + summary: Info for a specific fixture + operationId: showFixtureById + tags: + - fixtures + parameters: + - name: fixtureId + in: path + required: true + description: The id of the fixture to retrieve + schema: + type: string + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Fixture" + + /light_fixtures/{fixtureId}/light_channels: + get: + description: Returns all channels from a fixture + responses: + '200': + description: A list of channels. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Channel' + +components: + schemas: + Sensor: + type: object + required: + - id + properties: + name: + type: string + info: + type: string + version: + type: string + location: + ***TODO: LOCATION FORMAT*** general.md#location-data + info: + ***TODO: INFO FORMAT*** general.md#info-data + age: + type: integer + format: int32 + minimum: 0 + Sensors: + type: array + items: + $ref: "#components/schemas/Sensor" + Measurement: + type: object + required: + - id + properties: + id: + description: Unique id of the device + type: string + timestamp: + description: UTC timestamp of the measurement + type: string + red: + description: Level of red spectrum light + type: string + blue: + description: Level of blue spectrum light + type: string + green: + description: Level of green spectrum light + type: string + uv: + description: Level of ultraviolet light + type: string + infrared: + description: Level of infrared light + type: string + par: + description: Level of absorbable light + type: string + light: + description: Level of all spectrums of light + type: string + Measurements: + type: array + items: + $ref: "#components/schemas/Measurement" + Fixture: + type: object + required: + - id + - status + properties: + id: + description: Unique id of the fixture + type: string + name: + type: string + status: + description: The active state of the light ('on' or 'off') + type: string + Fixtures: + type: array + items: + $ref: "#components/schemas/Fixture" + Channel: + type: object + required: + - id + properties: + id: + description: Unique id of the channel + lo-color: + description: Lower boundary of the frequency range for a color channel + format: ***TODO FORMAT nm*** + hi-color: + description: Upper boundary of the frequency range for a color channel + format: ***TODO FORMAT nm*** + cct: + description: Color temperature for a white channel + format: ***TODO FORMAT K (Kelvin)*** + intensity: + description: Light intensity + format: ***TODO FORMAT %*** + Channels: + type: array + items: + $ref: "#components/schemas/Channel" diff --git a/versions/master/lights.md b/versions/master/lights.md index c777375..96361ff 100644 --- a/versions/master/lights.md +++ b/versions/master/lights.md @@ -1,259 +1,3 @@ -## Example Document Snippets - -```yaml -/light_sensors: - get: - description: Returns all sensors from the system that the user has access to - responses: - '200': - description: A list of sensors. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Sensor' -/light_sensors/{sensorId}: - get: - summary: Info for a specific sensor - operationId: showSensorById - tags: - - sensors - parameters: - - name: sensorId - in: path - required: true - description: The id of the sensor to retrieve - schema: - type: string - responses: - '200': - description: Expected response to a valid request - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Sensors" - default: - description: unexpected error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - -/light_sensors/{sensorId}/measurements: - get: - description: Returns spectrum measurements from a specific sensor - parameters: - - name: type - in: query - required: false - description: ppf or ppfd, defaults to ppfd - schema: - type: string - responses: - '200': - description: A list of measurements - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/SpectrumMeasurement' - -/zone/{zoneId}/sensors: - get: - description: Returns all sensors from a zone - responses: - '200': - description: A list of sensors. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Sensor' - -light_sensors: - get: - description: Returns all sensors from a zone - responses: - '200': - description: A list of sensors. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Sensor' - -light_fixtures: - get: - description: Returns all fixtures that a user has access to - responses: - '200': - description: A list of fixtures. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Fixture' - -/light_fixtures/{fixtureId}: - get: - summary: Info for a specific fixture - operationId: showFixtureById - tags: - - fixtures - parameters: - - name: fixtureId - in: path - required: true - description: The id of the fixture to retrieve - schema: - type: string - responses: - '200': - description: Expected response to a valid request - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Fixture" - - -/light_fixtures/{fixtureId}/light_channels: - get: - description: Returns all channels from a fixture - responses: - '200': - description: A list of channels. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Channel' -``` - -## Example Schema - -### Sensor - -```yaml -type: object -required: -- id -properties: - name: - type: string - info: - type: string - version: - type: string - location: - ***TODO: LOCATION FORMAT*** general.md#location-data - info: - ***TODO: INFO FORMAT*** general.md#info-data - age: - type: integer - format: int32 - minimum: 0 -``` - -### Measurement - -```yaml -type: object -required: -- id -properties: - id: - description: Unique id of the device - type: string - timestamp: - description: UTC timestamp of the measurement - type: string - red: - description: Level of red spectrum light - type: string - blue: - description: Level of blue spectrum light - type: string - green: - description: Level of green spectrum light - type: string - uv: - description: Level of ultraviolet light - type: string - infrared: - description: Level of infrared light - type: string - par: - description: Level of absorbable light - type: string - light: - description: Level of all spectrums of light - type: string -``` - -### Fixture - -```yaml -type: object -required: -- id -- status -properties: - id: - description: Unique id of the fixture - type: string - name: - type: string - status: - description: The active state of the light ('on' or 'off') - type: string -``` - -```yaml -type: object -required: -- id -properties: - name: - type: string - status: - description: The active state of the light ('on' or 'off') - type: string -``` - -### Channel - -```yaml -type: object -required: -- id -properties: - id: - description: Unique id of the channel - lo-color: - description: Lower boundary of the frequency range for a color channel - format: ***TODO FORMAT nm*** - hi-color: - description: Upper boundary of the frequency range for a color channel - format: ***TODO FORMAT nm*** - cct: - description: Color temperature for a white channel - format: ***TODO FORMAT K (Kelvin)*** - intensity: - description: Light intensity - format: ***TODO FORMAT %*** -``` - - ## Example requests ### Sensors