Module RESTful API

The API allows you to use the function of each module.
The basic components like URL structure, versioning and error handling are generic over all modules.

Guide for rapid implementation

This guide is intended to enable a quick implementation and explain the most important points.

1. Implement the version check and device selection.
   This point is very important because we don’t want problematic implementations that go crazy after an update!
2. Implement proper error handling.
3. After the version check and device selection reset the device to initial state using /reset.
   This is not needed if the application uses only “read” requests.
4. Start by implementing all the GET requests and proceed with POST requests later.
5. Some functions like /hard_reset, /watchdog or /limits can reset the entire system.
   We do not recommend to implement them if they are not needed by the application!
6. Implement the /notification endpoint if it is required by the documentation.

Important notes

Multicast DNS auto detection

The API can be detected using mDNS queries.

The service type are “_https._tcp” and “_https._tcp”.
The configuration may be extended by additional txt records in the future. You can find the latest config under /etc/avahi/services/nexus-rest-*.service

The mDNS config (avahi) looks like this:

<service-group>
  <name replace-wildcards="yes">NOREYA NEXUS IO Module API (%h)</name>
  <service>
    <type>_http._tcp</type>
    <port>80</port>
    <txt-record>vendor=noreyatech</txt-record>
    <txt-record>path=/api/io/</txt-record>
    <txt-record>service=io-module</txt-record>
    <txt-record>machine-id=/nexus-machine-id</txt-record>
    <txt-record>tls-ca=/noreya-nexus/certificates/ca.pem</txt-record>
  </service>
  <service>
    <type>_https._tcp</type>
    <port>443</port>
    <txt-record>vendor=noreyatech</txt-record>
    <txt-record>path=/api/io/</txt-record>
    <txt-record>service=io-module</txt-record>
    <txt-record>machine-id=/nexus-machine-id</txt-record>
    <txt-record>tls-ca=/noreya-nexus/certificates/ca.pem</txt-record>
  </service>
</service-group>

Secure communication via HTTPS

It is recommended to secure and trust the communication via HTTPS.
You can retrieve the certificate of the X.509/PEM certification authority via the path in the TXT entry “tls-ca”.
The TLS certificate is valid for the propagated host name and all other host names or IP addresses configured under : http://noreya-nexus.local/nexuscontrolui/system/settings#tls-cert

You should import this certificate on the client and use it for further communication (“trust on first connection strategy”).

Machine ID check

The mDNS implementation handles devices with the same hostname (noreya-nexus) by appending a number (noreya-nexus.local, noreya-nexus-2.local…).
This is great, but has one big problem: If you have 3 hosts and the second one goes offline, the third one gets the second number (noreya-nexus-2.local).
To avoid problems with this behavior, you need to check the unique machine-id provided by the path (plain/txt) in the TXT entry “machine-id”.
We recommend using static IPs or router-defined hostnames (.lan) to avoid this problem, but implementations must deal with this.