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/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/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/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 diff --git a/versions/master/lights.md b/versions/master/lights.md index 5f94ea8..96361ff 100644 --- a/versions/master/lights.md +++ b/versions/master/lights.md @@ -1,355 +1,64 @@ -# Purpose +## Example requests -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. +### Sensors -**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) - -**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) - -### 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** +**Retrieving sensor information** ``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/info +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid] ``` -Sends an array of [Info](general.md#info-data) -**Retrieving version information** +**Updating sensor information** ``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/version +PUT http://[domain:port]/agroapi/[version]/light_sensors/[sensorid] ``` -Returns an array of [Version](general.md#version-data) -**Retrieving location information** +**Retrieving spectrum measurements as PPF** ``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/location +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid]/measurements?type=ppf ``` -Returns an array of [Location](general.md#location-data) -**Sending location information** +**Retrieving spectrum measurements as PPFD** ``` -POST http://[domain:port]/agroapi/[version]/lights/sensors/location +GET http://[domain:port]/agroapi/[version]/light_sensors/[sensorid]/measurements?type=ppf ``` -Sends an array of [Location](general.md#location-data) -**Retrieving spectrum measurements as PPF** +**Retrieving information for all sensors** ``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/ppf +GET http://[domain:port]/agroapi/[version]/light_sensors ``` -Returns an array of [Light PPF](lights.md#light-ppf) -**Retrieving spectrum measurements as PPFD** +**Retrieving information for all sensors in a zone** ``` -GET http://[domain:port]/agroapi/[version]/lights/sensors/ppfd +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/light_sensors ``` -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) +### Fixtures -**Retrieving version information** +**Retrieving information for all fixtures** ``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/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/sensors/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/sensors/location +PUT http://[domain:port]/agroapi/[version]/light_fixtures/[fixtureid] ``` -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) +### Channels -### 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 -**Retrieving ID information** +**Retrieving channel configurations for a fixture** ``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info +GET http://[domain:port]/agroapi/[version]/light_fixtures/[fixture_id]/light_channels ``` -Returns [Info](general.md#info-data) -**Sending ID information** +**Updating channel configuration** ``` -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** +PUT http://[domain:port]/agroapi/[version]/light_channels/[channel_id] ``` -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 -``` -Returns [Fixture Configuration](lights.md#fixture-configuration) - -**Sending configuration information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config -``` -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) - -**Sending power state information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power -``` -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) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/version -``` -Returns an array of [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/location -``` -Returns an array of [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/location -``` -Sends an array of [Location](general.md#location-data) - -**Retrieving configuration information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/config -``` -Returns an array of [Fixture Configuration](lights.md#fixture-configuration) - -**Sending configuration information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/config -``` -Sends an array of [Fixture Configuration](lights.md#fixture-configuration) - -**Retrieving power state information** -``` -GET http://[domain:port]/agroapi/[version]/lights/fixtures/power -``` -Returns an array of [Fixture Power](lights.md#fixture-power) - -**Sending power state information** -``` -POST http://[domain:port]/agroapi/[version]/lights/fixtures/power -``` -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) - -**Retrieving version information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixture/[fixtureid]/version -``` -Returns an array of [Version](general.md#version-data) - -**Retrieving location information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location -``` -Returns an array of [Location](general.md#location-data) - -**Sending location information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location -``` -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) - -**Retrieving power state information** -``` -GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power -``` -Returns an array of [Fixture Power](lghts.md#fixture-power) - -**Sending power state information** -``` -POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power -``` -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" |