SolarNetwork provides a fully-managed Instruction Input Endpoint (ININ) HTTP integration layer that allows arbitrary control messages to be converted to SolarNode instructions, executed, and their results converted to an arbitrary response message. This can be used to integrate control systems that do not natively support the SolarNetwork API.

The system works like this:

• You create a Request Transform configuration that specifies a Request Transform Service supported by SolarNetwork. A Request Transform Service is responsible for taking some input message and converting it to native SolarNetwork node instructions.
• You create a Response Transform configuration that specifies a Response Transform Service supported by SolarNetwork. A Response Transform Service is responsible for taking node instruction results and converting them to some output format to send as the endpoint response.
• You create an Endpoint configuration that specifies attributes like the node ID and source ID to apply to the converted datum, and the Transform configuration to use. The Endpoint will define a unique Endpoint ID that becomes part of the HTTP URL used to post the measurement data to SolarNetwork.
• You create a Credential configuration that defines a username and password that must be included when posting the measurement data to SolarNetwork.
• You create an Endpoint Authorization configuration that associates the Credential with the Endpoint.

The XSLT Request Transform Service is one example of a Request Transform Service; it allows you to configure an XSLT stylesheet that can convert arbitrary XML or JSON data into a JSON array of node instructions. The XSLT Response Transform Service is one example of a Response Transform Service; it allows you to configure an XSLT stylesheet that can convert node instruction JSON into an arbitrary response value.

Once an Endpoint is configured with at least one Endpoint Authorization, messages can be sent to the endpoint via HTTP POST, to a URL in this form:

☝️ Note the {endpointId} portion of the URL must be changed to the ID of an actual Endpoint.

Either HTTP basic authorization must be included with an Autorization: Basic HTTP header or OAuth client credentials must be included with an Authorization: Bearer HTTP header, both using any valid credentials associated with the endpoint.

An example HTTP POST request to an Endpoint with ID d4f3d589-31fd-4005-b780-b0593f943910 looks like this:

POST /api/v1/instr/endpoint/d4f3d589-31fd-4005-b780-b0593f943910 HTTP/1.1
Authorization: Basic Zm9vYmFyOnNlY3JldA==
Accept: application/json
Content-Type: application/json
Host: din.solarnetwork.net:443
Content-Length: 21

{"groupId":"abc-123"}

OAuth client credentials authorization can be configured. You may request OAuth credentials by emailing us. Once you have obtained the credentials, you can configure the OAuth issuer URL as the Username on one of your Credential entities.

The following HTTP headers are utilized:

The request Accept and Content-Type HTTP headers must be provided. As long as the configured request transform supports the provided Content-Type value and the response transform supports the provided Accept value, the response Content-Type will be set to the request Accept value.

In the example POST request above, the response Content-Type would be application/json because of the request Accept value; it would look something like this:

HTTP/1.1 200
Date: Wed, 08 May 2024 03:55:23 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: close

{"something":"here"}

URL query parameters may be provided, and they will be passed to both the Request Transform and Response Transform entities configured on the endpoint. In addition, the nodeIds query parameter can be used to provide the node IDs to send the generated instructions to. This can be useful so a single Endpoint can process messages from many identical services, each with their own node ID values.

For example, a URL path that specifies node ID 123 and 234 looks like this (the https://din.solarnetwork.net prefix is omitted for brevity):

/api/v1/instr/endpoint/d4f3d589-31fd-4005-b780-b0593f943910?nodeIds=123,234

The request body can be compressed using the gzip compression scheme. Include a Content-Encoding HTTP header, like this:

Content-Encoding: gzip

The input message must be no more than 8 KB in length, otherwise an error will be returned. This limit applies to the uncompressed data, if HTTP gzip encoding is used.

The response will be the output generated by the Response Transform configured on the endpoint.

The response body can be returned compressed with gzip by including an Accept-Encoding: gzip HTTP header in the request.

A Request Transform Service is responsible for converting input messages into native SolarNetwork node instructions.

The XSLT Request Transform Service uses XSLT (that you provide) to transform XML or JSON messages into a JSON array of native SolarNetwork node instruction objects. It can thus handle a wide variety of input data forms and is a good choice when no other more specific Request Transform Service is available.

The native JSON that the XSLT must produce looks like this:

[
  {
    "nodeId": 123,
    "topic": "LatestDatum",
    "params": {
      "sourceIds":"meter/1,meter/2"
    }
  }
]

☝️ Note that the nodeId value is not needed in the JSON output if the Endpoint defines a nodeIds value.

A single node instruction object can be generated, like this:

{
  "nodeId": 123,
  "topic": "LatestDatum",
  "params": {
    "sourceIds":"meter/1,meter/2"
  }
}

The instruction parameters can also be generated as an array of name/value objects under a parameters property, like this:

{
  "nodeId": 123,
  "topic": "LatestDatum",
  "parameters": [
    {"name":"sourceIds", "value":"meter/1,meter/2"},
    {"name":"maxAge", "value":"60"},
  ]
}

The following request Content-Type values are supported:

• application/json
• application/*+json
• application/*+xml
• text/xml

XSLT up to version 3 is supported. The XSLT stylesheet you provide will not be allowed to resolve external entities or resources, so things like <xsl:import> are not supported. The following custom XPath functions are available, in the http://solarnetwork.net/xslt namespace:

The XSLT Transform Service has a Service ID of net.solarnetwork.central.inin.XsltRequestTransformService and accepts the following service properties:

The transform will be provided with the following input parameters, which you can access with XSLT <xsl:param> declarations:

A Request Transform Service is responsible for converting input messages into native SolarNetwork node instructions.

The XSLT Response Transform Service uses XSLT (that you provide) to transform node instruction JSON messages into the desired output response form. It can thus handle a wide variety of output data forms and is a good choice when no other more specific Response Transform Service is available.

The XSLT will always be passed a input-json parameter with the a JSON array of node instruction objects, like this:

The native JSON that the XSLT must produce looks like this:

[
  {
    "nodeId": 123,
    "topic": "LatestDatum",
    "state": "Completed",
    "params": {
      "sourceIds":"meter/1,meter/2"
    }
  }
]

See the XSLT runtime section of the XSLT Request Transform Service for information about the XSLT features available to this service.

This service allows any request Accept value.

The XSLT Transform Service has a Service ID of net.solarnetwork.central.inin.XsltResponseTransformService and accepts the following service properties:

The transform will be provided with the following input parameters, which you can access with XSLT <xsl:param> declarations:

Within SolarNetwork, the following entities are managed via the SolarUser Instruction Input Endpoint API:

Username and password details that can be associated with Endpoint Authorizations.

See the Credential API for details.

Request Transform Service configuration, which is specific to the Request Transform Service configured.

See the Request Transform API for details.

Response Transform Service configuration, which is specific to the Response Transform Service configured.

See the Response Transform API for details.

Defines a unique data input endpoint, with the Request Transform and Response Transform to use and a node IDs value to assign to the converted instructions.

See the Endpoint API for details.

Associates a username/password Credential to an Endpoint, allowing those credentials to be used to post data to the endpoint. Any number of Endpoint Authorization entities can be associated with a given Endpoint, and a given Credential can be associated with any number of Endpoint Authorizations. Or put another way, you can use the same credentials across different endpoints, and configure multiple credentials on a single endpoint.

See the Endpoint Authorization API for details.