From 85199eed77e9b71df4dca08f7efbd2ed90778d44 Mon Sep 17 00:00:00 2001 From: jondayton Date: Thu, 3 May 2018 12:44:39 -0400 Subject: [PATCH] separate into specification and examples --- versions/master/README.md | 158 +++++++++++++++++++++++++++++++--- versions/master/air.md | 14 +-- versions/master/general.md | 142 ++---------------------------- versions/master/light.md | 16 +--- versions/master/nutrients.md | 12 +-- versions/master/plan.md | 14 +-- versions/master/reservoirs.md | 12 +-- versions/master/roots.md | 12 +-- versions/master/soil.md | 12 +-- 9 files changed, 162 insertions(+), 230 deletions(-) diff --git a/versions/master/README.md b/versions/master/README.md index b4e8c62..fe6bbc3 100644 --- a/versions/master/README.md +++ b/versions/master/README.md @@ -1,13 +1,147 @@ # API Specification -This directory contains the various parts of the open API specification for exchanging data and operational control in indoor agricultural environments. - -The specification is divided into the following sub-sections to make it easier to follow... - -* **General** - contains all of the essential rules that need to be followed, including common concepts, common data structures, timestamp formats, error handling, and so on. -* **Plan** - specifies the API for interacting with the basic concepts of a well-planned facility (compartments, zones, crop varieties, and so on) -* **Lights** - specifies the API for interacting with lighting systems -* **Air** - specifies the API for interacting with air control systems (heating, cooling, ventilation, humidity, and so on) -* **Soil** - specifies the API for interacting with soil monitoring systems -* **Roots** - specifies the API for interacting with root monitoring systems -* **Reservoirs** - specifies the API for interacting with reservoir control systems -* **Nutrients** - specifies the API for monitoring nutrients +This specification is intended to define a standardized way of communicating real-time command-and-control data and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. This document does not set out to define an API but rather to specify a uniform way to build one. It does not seek to dictate endpoint names, server architecture, or security protocols. 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 of the OpenAPI specification. + +# Common Concepts + +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. + +# URL construction + +*Path elements within the URL...* +- The first element of all compliant apis MUST be "agroapi" +- The second element of all compliant apis MUST be the version number +- The third element of all compliant apis MUST be a domain identifier (e.g., "lights", "air", and so on) +- All elements after the third and before the final element are optional and SHOULD describe collections and / or a single member of a collection +- The final element of all compliant apis MUST identify the information or action that is the subject of the call + +*Structure of collections...* +- Collection identifiers MUST be plural +- Endpoints SHOULD NOT nest more than 2 collections deep (e.g., collection/{id}/collection/{id}) + +*Data structures...* +- Individual data points coming from the same device SHOULD be grouped in a structure with other data points that are related to the same topic + +# Error Handling + +In principle, a successful API call should return an HTTP status code of 200. An unsuccessful API call will return an HTTP status code of 550 and the body should contain an error code that has been properly documented by the owner of the API. + +The interpretation of error codes, including the text describing the error, will be left up to the API user based on their understanding of the error code documentation provided by the API owner. + +# Authentication + +*TBD* We've agreed on Oauth + +# Timestamps + +All monitoring data MUST be accompanied by a timestamp that includes year, month, day, hour, minute, second, and time zone. The format MUST be as follows… + +`[year]-[month]-[day]_[hour]-[min]-[sec]_[timezone]` + +Here is an example of a properly formatted timestamp… + +`2018-01-25_04-56-05_UTC` + +# Common Structures +Many concepts use the same data structures to report their essential information. Those structures are listed here. + +## Info Data +| Name | Description | Unit | +| ----------- | ----------------------------------------------- | ---- | +| id | ID of the entity | uid | +| zone | ID of the zone containing this entity | uid | +| compartment | ID of the compartment that contains this entity | uid | +| facility | ID of the facility that contains this entity | uid | + +## Version Data +| Name | Description | Unit | +| ------- | ------------------------------------------ | ---- | +| id | unique id of the device | uid | +| make | Name of the company that makes this device | text | +| model | Model number of this device | text | +| version | Version number of this device | text | + +## Location Data +| Name | Description | Unit | +| ---- | ------------------------------------------------------- | ---- | +| id | Unique id of this entity | uid | +| x | x coordinate of this entity within its parent container | m | +| y | y coordinate of this entity within its parent container | m | +| z | z coordinate of this entity within its parent container | m | + +## Dimension Data +| Name | Description | Unit | +| ------ | ----------------------- | ---- | +| id | Unique id of the entity | uid | +| length | Length of the entity | m | +| width | Width of the entity | m | +| height | Height of the entity | m | + +# Data Types +## Boolean +Used to express T/F, Y/N, or ON/OFF values +```json +type: object + required: + - name + - status + properties: + status: + type: bool +``` +## Integer +Used to express whole 4-byte numbers +```json +type: object + required: + - name + - value + properties: + value: + type: integer +``` +## Decimal +Used to express numbers with 8-byte decimal precision +```json +type: object + required: + - name + - value + properties: + value: + type: number + format: double +``` +## String +Used to send alphanumeric strings +```json +type: object + required: + - name + - text + properties: + text: + type: string +``` + +# Examples + +While there are multiple compliant ways to adhere to the API specification, we have compiled examples of API implementations to assist those who may be implementing for the first time. + +* [General](general.md) - Examples of common concepts, data structures, timestamp formats, error handling, and so on. +* [Plan](plan.md) - specifies the API for interacting with the basic concepts of a well-planned facility (compartments, zones, crop varieties, and so on) +* [Lights](lights.md) - specifies the API for interacting with lighting systems +* [Air](air.md) - specifies the API for interacting with air control systems (heating, cooling, ventilation, humidity, and so on) +* [Soil](soil.md) - specifies the API for interacting with soil monitoring systems +* [Roots](roots.md) - specifies the API for interacting with root monitoring systems +* [Reservoirs](reservoirs.md) - specifies the API for interacting with reservoir control systems +* [Nutrients](nutrients.md) - specifies the API for monitoring nutrients diff --git a/versions/master/air.md b/versions/master/air.md index d8660f5..5ef9a20 100644 --- a/versions/master/air.md +++ b/versions/master/air.md @@ -1,14 +1,4 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of air quality and to allow data collection between control systems and / or peripheral devices. - -# 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. +# Examples: Air # Endpoints ## Sensors @@ -19,4 +9,4 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S | temp | The temperature of the air | celsius | | humidity | The level of humidity in the air | % | | co2 | The level of CO2 in the air | ppm | -| airflow | The speed of the airflow | m3/s | \ No newline at end of file +| airflow | The speed of the airflow | m3/s | diff --git a/versions/master/general.md b/versions/master/general.md index a6490f2..7d6ffb4 100644 --- a/versions/master/general.md +++ b/versions/master/general.md @@ -1,21 +1,8 @@ -# Purpose +# Examples: General -This specification is intended to define a standardized way of communicating real-time command-and-control data and to allow data collection between control systems and / or peripheral devices. +The diagram below captures a common structure of a company with several facilities. This document gives examples on a way in which the API could be implemented within that system. -# Scope - -The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. This document does not set out to define an API but rather to specify a uniform way to build one. It does not seek to dictate endpoint names, server architecture, or security protocols. 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. - -# Common Concepts - -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. -The diagram below captures their essential relationships. - -![Common Concepts](https://docs.google.com/drawings/d/e/2PACX-1vRptSa5X7K6yzOqA95Jpncwwl8rUZgxOo6l13m_VcnCyd5dHmlLZvUyrED-HX2b5Q9YNHiBltB6cY5t/pub?w=982&h=1042) +![Common Structure](https://docs.google.com/drawings/d/e/2PACX-1vRptSa5X7K6yzOqA95Jpncwwl8rUZgxOo6l13m_VcnCyd5dHmlLZvUyrED-HX2b5Q9YNHiBltB6cY5t/pub?w=982&h=1042) ## Company @@ -43,9 +30,9 @@ A zone identifies an area within a compartment dedicated to maintaining a micro- Every zone contains zero or more zones and / or devices. Every device that is deployed should be assigned to the correct zone. Zones are a natural way of grouping devices for control purposes, so that a configuration can be pushed to a zone and affect all relevant devices within the zone at the same time. -All zones must be able to identify the crop variety they are overseeing. All data produced from a zone must include a crop variety ID for easy identification. +In this example, zones identify the crop variety they are overseeing, and include a crop variety ID for easy identification. -Each zone must be able to identify its size (in width and height) as well as its relative location within the compartment, since all sensors and controllers within that zone will report their location relative to the zone, not the compartment. +Each zone identifies its size (in width and height) as well as its relative location within the compartment, since all sensors and controllers within that zone will report their location relative to the zone, not the compartment. Zones can be combined into deep hierarchies. For example, a compartment can have multiple rows of plants that are 1 foot off the floor (e.g., lettuce), with an additional layer of plants 4 feet off the floor (e.g., strawberries). The grower would want to create unique zones for the lettuce vs. the strawberries, reflecting their unique feeds for irrigation and supplemental lighting. However, the grower would also want to maintain a general climate zone for the overall compartment for the purposes of controlling heating and ventilation. This means that the compartment would have a global zone containing two sub-zones. @@ -57,7 +44,7 @@ Every device and zone should know its position relative to its container (device A device refers to any physical mechanism that can either monitor or control the growing environment (lights, pumps, heaters, humidifiers, etc). -Every device must be related to a zone and a location within that zone. It should be able to report these relationships along with its own unique ID. +In the example, every device is related to a zone and a location within that zone. It should be able to report these relationships along with its own unique ID. ## Sensor @@ -71,128 +58,11 @@ A controller refers to any device that can affect the growing environment (light The detailed endpoint structure is outside the scope of this document because it needs to make sense for the overall architecture of the implementation. However, there are a few standards that need to be considered when it comes to endpoint design. -*Path elements within the URL...* -- The first element of all compliant apis MUST be "agroapi" -- The second element of all compliant apis MUST be the version number -- The third element of all compliant apis MUST be a domain identifier (e.g., "lights", "air", and so on) -- All elements after the third and before the final element are optional and SHOULD describe collections and / or a single member of a collection -- The final element of all compliant apis MUST identify the information or action that is the subject of the call - -*Structure of collections...* -- Collection identifiers MUST be plural -- Endpoints SHOULD NOT nest more than 2 collections deep (e.g., collection/{id}/collection/{id}) - -*Data structures...* -- Individual data points coming from the same device SHOULD be grouped in a structure with other data points that are related to the same topic **Example** GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey -# Error Handling - -In principle, a successful API call should return an HTTP status code of 200. An unsuccessful API call will return an HTTP status code of 550 and the body should contain an error code that has been properly documented by the owner of the API. - -The interpretation of error codes, including the text describing the error, will be left up to the API user based on their understanding of the error code documentation provided by the API owner. - -# Validation Handshake - -*TBD* - -Although a data consumer / receiver will have its own limits when it comes to value ranges and so on, there is a perceived need for the consumer / receiver to know what value ranges the data producer / sender might provide. This gives the consumer / receiver a secondary validation check to ensure that the data makes sense. - -# Timestamps - -All monitoring data MUST be accompanied by a timestamp that includes year, month, day, hour, minute, second, and time zone. The format MUST be as follows… - -```[year]-[month]-[day]_[hour]-[min]-[sec]_[timezone]``` - -Here is an example of a properly formatted timestamp… - -```2018-01-25_04-56-05_UTC``` - -# Common Structures -Many concepts use the same data structures to report their essential information. Those structures are listed here. - -## Info Data -| Name | Description | Unit | -| ----------- | ----------------------------------------------- | ---- | -| id | ID of the entity | uid | -| zone | ID of the zone containing this entity | uid | -| compartment | ID of the compartment that contains this entity | uid | -| facility | ID of the facility that contains this entity | uid | - -## Version Data -| Name | Description | Unit | -| ------- | ------------------------------------------ | ---- | -| id | unique id of the device | uid | -| make | Name of the company that makes this device | text | -| model | Model number of this device | text | -| version | Version number of this device | text | - -## Location Data -| Name | Description | Unit | -| ---- | ------------------------------------------------------- | ---- | -| id | Unique id of this entity | uid | -| x | x coordinate of this entity within its parent container | m | -| y | y coordinate of this entity within its parent container | m | -| z | z coordinate of this entity within its parent container | m | - -## Dimension Data -| Name | Description | Unit | -| ------ | ----------------------- | ---- | -| id | Unique id of the entity | uid | -| length | Length of the entity | m | -| width | Width of the entity | m | -| height | Height of the entity | m | - -# Data Types -## Boolean -Used to express T/F, Y/N, or ON/OFF values -```json -type: object - required: - - name - - status - properties: - status: - type: bool -``` -## Integer -Used to express whole 4-byte numbers -```json -type: object - required: - - name - - value - properties: - value: - type: integer -``` -## Decimal -Used to express numbers with 8-byte decimal precision -```json -type: object - required: - - name - - value - properties: - value: - type: number - format: double -``` -## String -Used to send alphanumeric strings -```json -type: object - required: - - name - - text - properties: - text: - type: string -``` - # Primitive Endpoints The following endpoints provide examples of payloads that would be exchanged for any endpoints that are trying to work with simple primitive values (e.g., a single number, boolean flag, or piece of text). diff --git a/versions/master/light.md b/versions/master/light.md index 51e4e34..9759ce8 100644 --- a/versions/master/light.md +++ b/versions/master/light.md @@ -1,16 +1,4 @@ -# 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. +# Examples: Lights # Endpoints ## Sensors @@ -97,7 +85,7 @@ Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/m | --------- | -------------------------------- | -------- | | id | Unique id of the device | uid | | timestamp | UTC timestamp of the measurement | datetime | -| red | Level of red spectrum light | PPF | +| 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 | diff --git a/versions/master/nutrients.md b/versions/master/nutrients.md index 7757c01..8108c64 100644 --- a/versions/master/nutrients.md +++ b/versions/master/nutrients.md @@ -1,14 +1,4 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. - -# 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. +# Examples: Nutrients # Endpoints ## Sensors diff --git a/versions/master/plan.md b/versions/master/plan.md index 3862dbb..e63193e 100644 --- a/versions/master/plan.md +++ b/versions/master/plan.md @@ -1,17 +1,7 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with facility planning systems for planning the layout of a facility and the deployment of monitoring and control systems. - -# 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. +# Examples: Plan # Endpoints -The relationship between the common concepts (facilities, compartments, zones, etc) is maintained as part of a Plan that can be interrogated. The following URLs MUST be supported by any service that wishes to interact with a Plan. +The relationship between the common concepts (facilities, compartments, zones, etc) is maintained as part of a Plan that can be interrogated. ## Facilities ### All facilities diff --git a/versions/master/reservoirs.md b/versions/master/reservoirs.md index 5d799f1..0a6358d 100644 --- a/versions/master/reservoirs.md +++ b/versions/master/reservoirs.md @@ -1,14 +1,4 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of reservoir systems and to allow data collection between systems and / or peripheral devices. - -# 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. +# Examples: Reservoirs # Endpoints ## Sensors diff --git a/versions/master/roots.md b/versions/master/roots.md index ad1dba4..00eb077 100644 --- a/versions/master/roots.md +++ b/versions/master/roots.md @@ -1,14 +1,4 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. - -# 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. +# Examples: Roots # Endpoints ## Sensors diff --git a/versions/master/soil.md b/versions/master/soil.md index 980da37..89f87b9 100644 --- a/versions/master/soil.md +++ b/versions/master/soil.md @@ -1,14 +1,4 @@ -# Purpose - -This specification is intended to define a standardized way of communicating with soil systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices. - -# 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. +# Examples: Soil # Endpoints ## Sensors