Issues and notes from previous meetings #1
Description
General notes, we can move these to the appropriate areas of the repo when appropriate
Appendix A - General Agreements
This document is meant to reflect a discussion between the following participants (and we are trying to grow this list)…
- Motorleaf (QC, Canada)
- Agrilyst (New York)
- Lumigrow (California)
- Autogrow (New Zealand)
- Priva (Netherlands)
- Argus (BC, Canada)
- Link4 Corporation (California)
This section is divided into categories of discussion with questions and decisions listed in each one.
API protocol
Questions
- What technology stack should we use? REST?
- How do we format data? JSON?
- Do devices stream their data directly to receiving services? Are those receiving services on-site or in the cloud?
- Is communication only in the cloud? Can the cloud call a local system? Should a local system speak to another local system?
Decisions
- 26 Jan 2017 - Use REST over SSL carrying a JSON payload for all APIs
- 26 Jan 2017 - Lumigrow is concerned about whether they can stream real-time to a receiving service on-site or whether such a service could handle thousands of incoming calls per second
Architecture
Questions
- Do devices stream their data directly to receiving services? Are those receiving services on-site or in the cloud?
- Is communication only in the cloud? Can the cloud call a local system? Should a local system speak to another local system?
Decisions
- Cloud systems should not be calling local systems. Instead local systems should be calling cloud services that support this specification.
- On-site systems tend to prefer outbound communication to a known service. Where the vendor does not have a cloud service, those systems provide an API that other on-premise systems can call. A standardized API would allow any on-site system to be configured to call out to a compatible cloud service, knowing that this service was trusted by the customer.
- Argus currently allows others to call its system (inbound) using a REST API, but only on-site systems can make those calls and control is not possible (inbound calls are not trusted)
- Priva is creating its own cloud service in Azure that will receive its data through outbound calls in order to make it available to other cloud services
- Lumigrow currently makes outbound calls its own cloud service to deliver its data so that other cloud services can have access to it
Version Control
Questions
- How do we specify the version of the API being used?
- How do we roll out new versions? By call? By group of calls? Entire call set?
Decisions
- Version should be specified in the URL of the REST API
- The specific layout of the URL does not matter so long as it conforms to REST principles
Security
Questions
- Authentication using API tokens? SAML?
- Do data payloads need to be encrypted?
Decisions
- 26 Jan 2017 - Use an API key to keep it simple (need to figure out how to expire a key, if necessary)
- 26 Jan 2017 - Ephemeral SSL keys will avoid man-in-the-middle attacks
Categories of APIs
Questions
- Why do people need access to data?
- What types of APIs have the highest priority for this group?
- How will clients typically interact with such APIs?
Decisions
- 26 Jan 2017 - Data is needed for the following reasons…
- To drive real-time command-and-control
- To drive analysis, such as predictions, trends, etc
- To drive on-demand reporting
- 26 Jan 2017 - Here are the various types of APIs we might define…
- Pushing raw analytical data
- Pushing summarized analytical data
- Pulling summarized analytical data
- Pulling control commands
- Pushing events
- Pulling events
- 26 Jan 2017 - Historical analytical data appears to have the highest priority for the group
- 26 Jan 2017 - Command-and-Control features require real-time data (for alarms, fast reaction, etc)
- 26 Jan 2017 - Analysis features require summary data (i.e., historical data)
- 26 Jan 2017 - Some systems will want to build up their internal history and manage their own data, so they will pull the latest summary data at all times (and might start by pulling as much history as they can when they initially connect)
- 26 Jan 2017 - Any outages in connectivity might result in client systems pulling any data they missed during the outage
- 26 Jan 2017 - If near-real-time summary data is required, then we will need to support a callback / webhook approach, which might be more complicated to implement. However, the group could open-source a library to make it easier for everyone. Having said that, the general consensus seems to be that near-real-time summary data might not be required.
Data Model
Questions
- What are the different categories of data?
- How do we define a customer, a site, a device, zone?
- Can we standardize the data models?
- Can we define a best practice for configurations?
Decisions
- There are two types of data:
- Configurations
- Measurements
- Payload requires version control
- Payloads will need to be vendor-specific
- Systems will need to declare compatibility with specific vendors
- Data can be delivered in key-values
- The way that the data semantics are expressed should be standardized
- Tools like Swagger can help APIs be self-documenting (swagger.io)
- IDs for devices, sites, zones, and so on should be based on configurations
Specification Structure
Questions
- What is the base requirement for compliance?
- Do we divide compliance levels into spec versions (like SNMP)? Or do we use categories of compliance?
Decisions
- (8 Feb 2018) Argus Controls has created a framework spec document as a starting point. Available for review and editing: https://docs.google.com/document/d/1nDabvXG4t1t5i9WNCaFeFciZKO7Kb_H39OpnKIKcl5g/edit?usp=sharing
Publication
Questions
- How will this spec be published?
Decisions
- Each member organization would be free to publish the spec as a document on their web site
- Each member organization would be free to engage in any marketing efforts to promote the spec and their compliance with it (blogs, campaigns, and so on)
Standards Body
Questions
- Who should evolve and maintain this spec in the future?
Decisions
- 15 Feb 2018 - Jon Dayton and Jonathan Ginter will discuss this separately