Skip to content

SolarUser ININ API

Jump to bottom Edit New page
Matt Magoffin edited this page Jun 4, 2024 · 3 revisions

The SolarUser Instruction Input Endpoint API (ININ) provides methods to manage HTTP integration endpoint entities within SolarNetwork that allow arbitrary control messages to be executed as SolarNode instructions with their execution results converted to an arbitrary response message. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

For general information about ININ support in SolarNetwork see the Instruction Input Endpoint guide.

⚠️ Note that some changes made to these entities may not reflect immediately in endpoints actively processing data. Please wait up to 10 minutes for the changes to propagate fully.

API Endpoints

The following endpoint paths are all relative to the base path /solaruser/api/v1/sec/user/inin:

Verb Endpoint Description
POST /credentials Create credential
GET /credentials List credentials
GET /credentials/{credentialId} View credential
PUT /credentials/{credentialId} Update credential
DELETE /credentials/{credentialId} Delete credential
POST /credentials/{credentialId}/enabled/{enabled} Update credential enabled status
POST /request-transforms Create request transform
GET /request-transforms List request transforms
GET /request-transforms/{transformId} View request transform
PUT /request-transforms/{transformId} Update request transform
DELETE /request-transforms/{transformId} Delete request transform
POST /request-transforms/{transformId}/enabled/{enabled} Update request transform enabled status
POST /response-transforms Create response transform
GET /response-transforms List response transforms
GET /response-transforms/{transformId} View response transform
PUT /response-transforms/{transformId} Update response transform
DELETE /response-transforms/{transformId} Delete response transform
POST /response-transforms/{transformId}/enabled/{enabled} Update response transform enabled status
POST /endpoints Create endpoint
GET /endpoints List endpoints
GET /endpoints/{endpointId} View endpoint
PUT /endpoints/{endpointId} Update endpoint
DELETE /endpoints/{endpointId} Delete endpoint
POST /endpoints/{endpointId}/enabled/{enabled} Update endpoint enabled status
POST /endpoints/{endpointId}/preview Preview the endpoint conversion
GET /endpoints/auths List endpoint authorizations
GET /endpoints/{endpointId}/auths/{credentialId} View endpoint authorization
PUT /endpoints/{endpointId}/auths/{credentialId} Save endpoint authorization
DELETE /endpoints/{endpointId}/auths/{credentialId} Delete endpoint authorization
POST /endpoints/{endpointId}/auths/{credentialId}/enabled/{enabled} Update endpoint authorization enabled status
GET /services/request-transform List the available Request Transform services.
GET /services/response-transform List the available Response Transform services.

Date formatting

For endpoints that return timestamp values (full date and time) the timestamps will be rendered as string values using the ISO 8601 timestamp format YYYY-MM-dd HH:mm:ss.SSSSSS'Z' in the UTC time zone, for example 2020-03-01 10:30:49.346827Z. The fractional second can contain up to 6 digits for nanosecond level precision, and will only display up to the precision set in the timestamp. That means the fractional seconds might not appear if the timestamp has no fractional seconds.

For endpoints that accept timestamp values, the same ISO 8601 timestamp format is required, however the fractional seconds may be omitted. For example 2020-03-01 10:30:49Z is a valid value.

Credentials

Credential entities define username and password details that can be associated with Endpoint Authorizations. A single Credential can be associated with any number of Endpoint Authorizations, and a single Endpoint Authorization can be associated with any number of Credentials.

Credential create

This method creates a new Credential entity. An application/json request body must be provided with the credential details to create.

POST /solaruser/api/v1/sec/user/inin/credentials

The request body accepts a Credential JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
username String The username. The username must be unique within your SolarNetwork account.
password String The password.
oauth Boolean Enable to use OAuth client credentials authorization.

For example:

{"username":"my-user","password":"my-secret","enabled":true,"oauth":false}

The response will be a Credential entity object that provides the ID assigned to the new Credential. See Credential view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/inin/credentials/1

Credential OAuth support

The OAuth client credentials authorization flow can be used by setting the oauth property to true. The username property must be configured with a URL in the form of {issuerUrl}/{clientId}, for example https://id.example.com/pool-abcxyz/abc123def467 configures abc123def467 as the OAuth client ID, issued by https://id.example.com/pool-abcxyz. The password property is not necessary in this configuration, and will be ignored.

Credential list

This method returns a list of Credential entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/inin/credentials

The request body accepts the following search filter query parameters:

Property Type Description
credentialId Number The ID of a credential to match.
credentialIds Array<Number> A comma-delimited list of credential IDs to match (logical OR).
enabled Boolean The desired enabled state to match.
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Credential entity objects. See the Credential view response for details.

Credential view

This method returns a Credential entity.

GET /solaruser/api/v1/sec/user/inin/credentials/{credentialId}
credentialId The ID of the Credential to view.

Credential view response

The response will be a Credential entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
credentialId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator. Only enabled entities will be considered during authorization.
username String The username.
expires String The optional expiration date.
expired Boolean true if the expires date is defined and is before the current date.
oauth Boolean true to use OAuth client credentials authorization.

⚠️ Note that the password provided when the Credential was created or updated will not be returned.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "credentialId": 2,
    "created": "2024-02-26 04:09:40.498708Z",
    "modified": "2024-02-26 04:09:40.498708Z",
    "enabled": true,
    "username": "test",
    "expired": false,
    "oauth": false
  }
}

Credential update

This method updates an existing Credential entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/inin/credentials/{credentialId}
credentialId The ID of the Credential to update.

The request body accepts a Credential JSON object as specified in the Credential create method.

Credential delete

This method deletes a Credential entity. All Endpoint Authorization entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/inin/credentials/{credentialId}
credentialId The ID of the Credential to delete.

Credential update enabled

This method updates the enabled status of a Credential entity.

POST /solaruser/api/v1/sec/user/inin/credentials/{credentialId}/enabled/{enabled}
credentialId The ID of the Credential to update.
enabled The desired enabled state to set.

Request Transforms

Request Transform entities define input control message conversions to native SolarNode instructions, by configuring a Request Transform Service along with any settings supported by that service. A Request Transform entity can be associated with any number of Endpoints.

Request Transform create

This method creates a new Request Transform entity. An application/json request body must be provided with the transform details to create.

POST /solaruser/api/v1/sec/user/inin/request-transforms

The request body accepts a Request Transform JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
serviceIdentifier String The Service ID of the Request Transform Service to use.
serviceProperties Object Transform Service-specific settings to use.

For example:

{
  "name": "Meter XML",
  "enabled": "true",
  "serviceIdentifier": "net.solarnetwork.central.din.XsltTransformService",
  "serviceProperties": {
    "xslt": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/request-transform\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:math=\"http://www.w3.org/2005/xpath-functions/math\" exclude-result-prefixes=\"xs math\" version=\"3.0\"><xsl:output method=\"text\"/><!-- Support both a root-level <data/> element or a nested list like <array><data/><data/></array> --><xsl:template match=\"/\"><xsl:if test=\"count(//data) gt 1\">[</xsl:if><xsl:apply-templates select=\"//data\"/><xsl:if test=\"count(//data) gt 1\">]</xsl:if></xsl:template><xsl:template match=\"data\"><xsl:if test=\"position() gt 1\">,</xsl:if><!-- Always generate a \"created\" property so it is easier to generate all subsequent properties with a leading comma character. --><xsl:text>{\"created\":\"</xsl:text><xsl:value-of select=\"if (exists(@ts)) then @ts else current-dateTime()\"/><xsl:text>\"</xsl:text><xsl:choose><xsl:when test=\"number(@node) eq number(@node)\"><xsl:text>,\"nodeId\":</xsl:text><xsl:value-of select=\"@node\"/></xsl:when><xsl:when test=\"number(@location) eq number(@location)\"><xsl:text>,\"locationId\":</xsl:text><xsl:value-of select=\"@location\"/></xsl:when></xsl:choose><xsl:if test=\"exists(@source)\"><xsl:text>,\"sourceId\":\"</xsl:text><xsl:value-of select=\"@source\"/><xsl:text>\"</xsl:text></xsl:if><!-- Convert all <prop> values that are numbers into instantaneous datum properties. --><xsl:variable name=\"instantaneous\" select=\"prop[number() eq number()]\"/><xsl:if test=\"count($instantaneous) gt 0\"><xsl:text>,\"i\":{</xsl:text><xsl:apply-templates select=\"$instantaneous\"/><xsl:text>}</xsl:text></xsl:if><xsl:variable name=\"status\" select=\"./prop[number() ne number()]\"/><xsl:if test=\"count($status) gt 0\"><xsl:text>,\"s\":{</xsl:text><xsl:apply-templates select=\"$status\"/><xsl:text>}</xsl:text></xsl:if><xsl:text>}</xsl:text></xsl:template><xsl:template match=\"prop\"><xsl:if test=\"position() gt 1\"><xsl:text>,</xsl:text></xsl:if><xsl:text>\"</xsl:text><xsl:value-of select=\"@name\"/><xsl:text>\":</xsl:text><xsl:variable name=\"isNumber\" select=\"number() eq number()\"/><xsl:if test=\"not($isNumber)\"><xsl:text>\"</xsl:text></xsl:if><xsl:value-of select=\".\"/><xsl:if test=\"not($isNumber)\"><xsl:text>\"</xsl:text></xsl:if></xsl:template></xsl:stylesheet>"
  }
}

The response will be a Request Transform entity object that provides the ID assigned to the new Transform. See Request Transform view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/inin/request-transforms/1

Request Transform list

This method returns a list of Request Transform entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/inin/request-transforms

The request body accepts the following search filter query parameters:

Property Type Description
transformId Number The ID of a transform to match.
transformIds Array<Number> A comma-delimited list of transform IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Transform entity objects. See the Request Transform view response for details.

Request Transform view

This method returns a Request Transform entity.

GET /solaruser/api/v1/sec/user/inin/request-transforms/{transformId}
transformId The ID of the Transform to view.

Request Transform view response

The response will be a Request Transform entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
transformId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator. Only enabled entities will be considered during authorization.
name String The display name.
serviceIdentifier String The Service ID of the [Transform Service][xform-service] to use.
serviceProperties Object Transform Service-specific settings to use.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "transformId": 1,
    "created": "2024-02-23 05:34:52.307385Z",
    "modified": "2024-02-23 05:34:52.307385Z",
    "enabled": true,
    "name": "JSON Meter",
    "serviceIdentifier": "net.solarnetwork.central.din.XsltTransformService",
    "serviceProperties": {
      "xslt": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/request-transform\"\n    xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"\n    xpath-default-namespace=\"http://www.w3.org/2005/xpath-functions\" version=\"3.0\">\n\n    <xsl:param name=\"input-json\">\n        {\n            \"ts\": \"2024-02-22T12:00:00Z\",\n            \"node\": 123,\n            \"source\": \"test/1\",\n            \"props\": {\n                \"foo\": 123,\n                \"bim\": 234,\n                \"msg\": \"Hello\"\n            }\n        }\n    </xsl:param>\n\n    <xsl:mode on-no-match=\"deep-skip\"/>\n    <xsl:output method=\"text\"/>\n\n    <xsl:variable name=\"input-xml\" select=\"json-to-xml($input-json)\"/>\n    \n    <!--\n       The XML form in $input-xml looks like this:\n       \n        <map xmlns=\"http://www.w3.org/2005/xpath-functions\">\n        \t<string key=\"ts\">2024-02-22T12:00:00Z</string>\n        \t<number key=\"node\">123</number>\n        \t<string key=\"source\">test/1</string>\n        \t<map key=\"props\">\n        \t\t<number key=\"foo\">123</number>\n        \t\t<number key=\"bim\">234</number>\n        \t\t<string key=\"msg\">Hello</string>\n        \t</map>\n        </map>\n    -->\n\n    <xsl:template match=\"/\">\n        <xsl:apply-templates select=\"$input-xml/*\"/>\n    </xsl:template>\n\n    <xsl:template match=\"map[not(exists(@key))]\">\n        <xsl:text>{\"created\":\"</xsl:text>\n        <xsl:value-of select=\"\n                if (exists(string[@key = 'ts'])) then\n                    string[@key = 'ts']\n                else\n                    current-dateTime()\"/>\n        <xsl:text>\"</xsl:text>\n        <xsl:if test=\"exists(number[@key = 'node'])\">\n            <xsl:text>,\"nodeId\":</xsl:text>\n            <xsl:value-of select=\"number[@key = 'node']\"/>\n        </xsl:if>\n        <xsl:if test=\"exists(string[@key = 'source'])\">\n            <xsl:text>,\"sourceId\":\"</xsl:text>\n            <xsl:value-of select=\"string[@key = 'source']\"/>\n            <xsl:text>\"</xsl:text>\n        </xsl:if>\n        <!--\n            Convert all <map key=\"props\"><number> values into instantaneous datum properties.\n        -->\n        <xsl:variable name=\"instantaneous\" select=\"map[@key = 'props']/number\"/>\n        <xsl:if test=\"count($instantaneous) gt 0\">\n            <xsl:text>,\"i\":{</xsl:text>\n            <xsl:apply-templates select=\"$instantaneous\"/>\n            <xsl:text>}</xsl:text>\n        </xsl:if>\n        <!--\n            Convert all <map key=\"props\"><string> values into instantaneous datum properties.\n        -->\n        <xsl:variable name=\"status\" select=\"map[@key = 'props']/string\"/>\n        <xsl:if test=\"count($status) gt 0\">\n            <xsl:text>,\"s\":{</xsl:text>\n            <xsl:apply-templates select=\"$status\"/>\n            <xsl:text>}</xsl:text>\n        </xsl:if>\n        <xsl:text>}</xsl:text>\n    </xsl:template>\n\n    <xsl:template match=\"map[@key = 'props']/number\">\n        <xsl:if test=\"position() gt 1\">,</xsl:if>\n        <xsl:text>\"</xsl:text>\n        <xsl:value-of select=\"@key\"/>\n        <xsl:text>\":</xsl:text>\n        <xsl:value-of select=\".\"/>\n    </xsl:template>\n\n    <xsl:template match=\"map[@key = 'props']/string\">\n        <xsl:if test=\"position() gt 1\">,</xsl:if>\n        <xsl:text>\"</xsl:text>\n        <xsl:value-of select=\"@key\"/>\n        <xsl:text>\":\"</xsl:text>\n        <xsl:value-of select=\".\"/>\n        <xsl:text>\"</xsl:text>\n    </xsl:template>\n\n</xsl:stylesheet>"
    }
  }
}

Request Transform update

This method updates an existing Request Transform entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/inin/request-transforms/{transformId}
transformId The ID of the Request Transform to update.

The request body accepts a Request Transform JSON object as specified in the Transform create method.

Request Transform delete

This method deletes a Request Transform entity. All Endpoint Authorization entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/inin/request-transforms/{transformId}
transformId The ID of the Request Transform to delete.

Request Transform update enabled

This method updates the enabled status of a Request Transform entity.

POST /solaruser/api/v1/sec/user/inin/request-transforms/{transformId}/enabled/{enabled}
transformId The ID of the Request Transform to update.
enabled The desired enabled state to set.

Response Transforms

Transform entities define instruction execution result conversions, by configuring a Response Transform Service along with any settings supported by that service. A Response Transform entity can be associated with any number of Endpoints.

Response Transform create

This method creates a new Response Transform entity. An application/json response body must be provided with the transform details to create.

POST /solaruser/api/v1/sec/user/inin/response-transforms

The response body accepts a Response Transform JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
serviceIdentifier String The Service ID of the Response Transform Service to use.
serviceProperties Object Response Transform Service-specific settings to use.

For example:

{
  "name": "Meter XML",
  "enabled": "true",
  "serviceIdentifier": "net.solarnetwork.central.din.XsltTransformService",
  "serviceProperties": {
    "xslt": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/response-transform\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:math=\"http://www.w3.org/2005/xpath-functions/math\" exclude-result-prefixes=\"xs math\" version=\"3.0\"><xsl:output method=\"text\"/><!-- Support both a root-level <data/> element or a nested list like <array><data/><data/></array> --><xsl:template match=\"/\"><xsl:if test=\"count(//data) gt 1\">[</xsl:if><xsl:apply-templates select=\"//data\"/><xsl:if test=\"count(//data) gt 1\">]</xsl:if></xsl:template><xsl:template match=\"data\"><xsl:if test=\"position() gt 1\">,</xsl:if><!-- Always generate a \"created\" property so it is easier to generate all subsequent properties with a leading comma character. --><xsl:text>{\"created\":\"</xsl:text><xsl:value-of select=\"if (exists(@ts)) then @ts else current-dateTime()\"/><xsl:text>\"</xsl:text><xsl:choose><xsl:when test=\"number(@node) eq number(@node)\"><xsl:text>,\"nodeId\":</xsl:text><xsl:value-of select=\"@node\"/></xsl:when><xsl:when test=\"number(@location) eq number(@location)\"><xsl:text>,\"locationId\":</xsl:text><xsl:value-of select=\"@location\"/></xsl:when></xsl:choose><xsl:if test=\"exists(@source)\"><xsl:text>,\"sourceId\":\"</xsl:text><xsl:value-of select=\"@source\"/><xsl:text>\"</xsl:text></xsl:if><!-- Convert all <prop> values that are numbers into instantaneous datum properties. --><xsl:variable name=\"instantaneous\" select=\"prop[number() eq number()]\"/><xsl:if test=\"count($instantaneous) gt 0\"><xsl:text>,\"i\":{</xsl:text><xsl:apply-templates select=\"$instantaneous\"/><xsl:text>}</xsl:text></xsl:if><xsl:variable name=\"status\" select=\"./prop[number() ne number()]\"/><xsl:if test=\"count($status) gt 0\"><xsl:text>,\"s\":{</xsl:text><xsl:apply-templates select=\"$status\"/><xsl:text>}</xsl:text></xsl:if><xsl:text>}</xsl:text></xsl:template><xsl:template match=\"prop\"><xsl:if test=\"position() gt 1\"><xsl:text>,</xsl:text></xsl:if><xsl:text>\"</xsl:text><xsl:value-of select=\"@name\"/><xsl:text>\":</xsl:text><xsl:variable name=\"isNumber\" select=\"number() eq number()\"/><xsl:if test=\"not($isNumber)\"><xsl:text>\"</xsl:text></xsl:if><xsl:value-of select=\".\"/><xsl:if test=\"not($isNumber)\"><xsl:text>\"</xsl:text></xsl:if></xsl:template></xsl:stylesheet>"
  }
}

The response will be a Response Transform entity object that provides the ID assigned to the new Response Transform. See Response Transform view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/inin/response-transforms/1

Response Transform list

This method returns a list of Response Transform entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/inin/response-transforms

The response body accepts the following search filter query parameters:

Property Type Description
transformId Number The ID of a transform to match.
transformIds Array<Number> A comma-delimited list of transform IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Transform entity objects. See the Response Transform view response for details.

Response Transform view

This method returns a Response Transform entity.

GET /solaruser/api/v1/sec/user/inin/response-transforms/{transformId}
transformId The ID of the Response Transform to view.

Response Transform view response

The response will be a Response Transform entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
transformId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator. Only enabled entities will be considered during authorization.
name String The display name.
serviceIdentifier String The Service ID of the [Transform Service][xform-service] to use.
serviceProperties Object Transform Service-specific settings to use.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "transformId": 1,
    "created": "2024-02-23 05:34:52.307385Z",
    "modified": "2024-02-23 05:34:52.307385Z",
    "enabled": true,
    "name": "JSON Meter",
    "serviceIdentifier": "net.solarnetwork.central.din.XsltTransformService",
    "serviceProperties": {
      "xslt": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/response-transform\"\n    xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"\n    xpath-default-namespace=\"http://www.w3.org/2005/xpath-functions\" version=\"3.0\">\n\n    <xsl:param name=\"input-json\">\n        {\n            \"ts\": \"2024-02-22T12:00:00Z\",\n            \"node\": 123,\n            \"source\": \"test/1\",\n            \"props\": {\n                \"foo\": 123,\n                \"bim\": 234,\n                \"msg\": \"Hello\"\n            }\n        }\n    </xsl:param>\n\n    <xsl:mode on-no-match=\"deep-skip\"/>\n    <xsl:output method=\"text\"/>\n\n    <xsl:variable name=\"input-xml\" select=\"json-to-xml($input-json)\"/>\n    \n    <!--\n       The XML form in $input-xml looks like this:\n       \n        <map xmlns=\"http://www.w3.org/2005/xpath-functions\">\n        \t<string key=\"ts\">2024-02-22T12:00:00Z</string>\n        \t<number key=\"node\">123</number>\n        \t<string key=\"source\">test/1</string>\n        \t<map key=\"props\">\n        \t\t<number key=\"foo\">123</number>\n        \t\t<number key=\"bim\">234</number>\n        \t\t<string key=\"msg\">Hello</string>\n        \t</map>\n        </map>\n    -->\n\n    <xsl:template match=\"/\">\n        <xsl:apply-templates select=\"$input-xml/*\"/>\n    </xsl:template>\n\n    <xsl:template match=\"map[not(exists(@key))]\">\n        <xsl:text>{\"created\":\"</xsl:text>\n        <xsl:value-of select=\"\n                if (exists(string[@key = 'ts'])) then\n                    string[@key = 'ts']\n                else\n                    current-dateTime()\"/>\n        <xsl:text>\"</xsl:text>\n        <xsl:if test=\"exists(number[@key = 'node'])\">\n            <xsl:text>,\"nodeId\":</xsl:text>\n            <xsl:value-of select=\"number[@key = 'node']\"/>\n        </xsl:if>\n        <xsl:if test=\"exists(string[@key = 'source'])\">\n            <xsl:text>,\"sourceId\":\"</xsl:text>\n            <xsl:value-of select=\"string[@key = 'source']\"/>\n            <xsl:text>\"</xsl:text>\n        </xsl:if>\n        <!--\n            Convert all <map key=\"props\"><number> values into instantaneous datum properties.\n        -->\n        <xsl:variable name=\"instantaneous\" select=\"map[@key = 'props']/number\"/>\n        <xsl:if test=\"count($instantaneous) gt 0\">\n            <xsl:text>,\"i\":{</xsl:text>\n            <xsl:apply-templates select=\"$instantaneous\"/>\n            <xsl:text>}</xsl:text>\n        </xsl:if>\n        <!--\n            Convert all <map key=\"props\"><string> values into instantaneous datum properties.\n        -->\n        <xsl:variable name=\"status\" select=\"map[@key = 'props']/string\"/>\n        <xsl:if test=\"count($status) gt 0\">\n            <xsl:text>,\"s\":{</xsl:text>\n            <xsl:apply-templates select=\"$status\"/>\n            <xsl:text>}</xsl:text>\n        </xsl:if>\n        <xsl:text>}</xsl:text>\n    </xsl:template>\n\n    <xsl:template match=\"map[@key = 'props']/number\">\n        <xsl:if test=\"position() gt 1\">,</xsl:if>\n        <xsl:text>\"</xsl:text>\n        <xsl:value-of select=\"@key\"/>\n        <xsl:text>\":</xsl:text>\n        <xsl:value-of select=\".\"/>\n    </xsl:template>\n\n    <xsl:template match=\"map[@key = 'props']/string\">\n        <xsl:if test=\"position() gt 1\">,</xsl:if>\n        <xsl:text>\"</xsl:text>\n        <xsl:value-of select=\"@key\"/>\n        <xsl:text>\":\"</xsl:text>\n        <xsl:value-of select=\".\"/>\n        <xsl:text>\"</xsl:text>\n    </xsl:template>\n\n</xsl:stylesheet>"
    }
  }
}

Response Transform update

This method updates an existing Response Transform entity. An application/json response body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/inin/response-transforms/{transformId}
transformId The ID of the Response Transform to update.

The response body accepts a Respones Transform JSON object as specified in the Response Transform create method.

Response Transform delete

This method deletes a Response Transform entity. All Endpoint Authorization entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/inin/response-transforms/{transformId}
transformId The ID of the Response Transform to delete.

Response Transform update enabled

This method updates the enabled status of a Response Transform entity.

POST /solaruser/api/v1/sec/user/inin/response-transforms/{transformId}/enabled/{enabled}
transformId The ID of the Response Transform to update.
enabled The desired enabled state to set.

Endpoints

Endpoint entities define a unique instruction input URL, with an associated Request Transform to use for converting the input control message to SolarNetwork native SolarNode instructions and an associated Response Transform to use for converting the instruction execution results into the desired output control message response.

Endpoint create

This method creates a new Endpoint entity. An application/json request body must be provided with the endpoint details to create.

POST /solaruser/api/v1/sec/user/inin/endpoints

The request body accepts an Endpoint JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
nodeIds Array The node IDs to assign to converted instructions. Omit if the request transform itself generates the node IDs.
requestTransformId Number The ID of the Request Transform entity to use for converting the input message.
responseTransformId Number The ID of the Response Transform entity to use for converting the output message.
maxExecutionSeconds Number The maximum number of seconds to wait for node instructions to execute before timing out.
userMetadataPath String A user metadata path to extract from user metadata and provide to the transforms as a JSON string on the user-meta XSLT input parameter. For example /pm/tariffs/schedule-01.
requestContentType String An explicit HTTP request Content-Type value to assume on requests sent to the endpoint, overriding any value provided in the request. Leave empty to use the value provided in the request.
responseContentType String An explicit HTTP response Content-Type value to provide to requests sent to the endpoint, overriding any value provided in the HTTP request Accept header and the selected by the response transform.

For example:

{
  "name": "Meter XML",
  "nodeIds": [1],
  "requestTransformId": 1,
  "responseTransformId": 1,
  "enabled": true,
  "maxExecutionSeconds": 10
}

The response will be an Endpoint entity object that provides the ID assigned to the new Endpoint. See Endpoint view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/inin/endpoints/1

Endpoint list

This method returns a list of Endpoint entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/inin/endpoints

The request body accepts the following search filter query parameters:

Property Type Description
endpointId Number The ID of an endpoint to match.
endpointIds Array<Number> A comma-delimited list of endpoint IDs to match (logical OR).
enabled Boolean The desired enabled state to match.
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Endpoint entity objects. See the Endpoint view response for details.

Endpoint view

This method returns an Endpoint entity.

GET /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}
endpointId The ID of the Endpoint to view.

Endpoint view response

The response will be an Endpoint entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
endpointId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator. Only enabled entities will be considered during authorization.
name String A display name.
nodeIds Array The node IDs to assign to converted instructions. Omit if the request transform itself generates the node IDs.
requestTransformId Number The ID of the Request Transform entity to use for converting the input message.
responseTransformId Number The ID of the Response Transform entity to use for converting the output message.
maxExecutionSeconds Number The maximum number of seconds to wait for node instructions to execute before timing out.
requestContentType String An explicit HTTP request Content-Type value to assume on requests sent to the endpoint, overriding any value provided in the request. Leave empty to use the value provided in the request.
responseContentType String An explicit HTTP response Content-Type value to provide to requests sent to the endpoint, overriding any value provided in the HTTP request Accept header and the selected by the response transform.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "endpointId": "d4f3d589-31fd-4005-b780-b0593f943910",
    "created": "2024-02-23 05:28:38.268362Z",
    "modified": "2024-02-23 05:28:38.268362Z",
    "enabled": true,
    "name": "Meter XML",
    "nodeIds": [1],
    "requestTransformId": 1,
    "responseTransformId": 1,
    "maxExecutionSeconds": 10
  }
}

Endpoint update

This method updates an existing Endpoint entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}
endpointId The ID of the Endpoint to update.

The request body accepts an Endpoint JSON object as specified in the Endpoint create method.

Endpoint delete

This method deletes an Endpoint entity. All Endpoint Authorization entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}
endpointId The ID of the Endpoint to delete.

Endpoint update enabled

This method updates the enabled status of an Endpoint entity.

POST /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/enabled/{enabled}
endpointId The ID of the Endpoint to update.
enabled The desired enabled state to set.

Endpoint preview

Preview the request and response transforms on an arbitrary input message. An application/json request body must be provided with the preview details to process.

The body can be compressed using gzip if you include a Content-Encoding: gzip HTTP header, and the response body can be compressed using gzip if you include an Accept-Encoding: gzip HTTP header.

POST /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/preview
endpointId The ID of the Endpoint to update.

The request body accepts a JSON object with the following properties:

Property Type Description
contentType String The input message MIME type, e.g. application/json.
data String The input message content, as appropriate for the endpoint's configured Request Transform.
query String An optional URL query string, to simulate endpoint URL query parameters.
parameters Object Optional parameters to pass to the transforms.
instructionResults Array Instruction result objects to simulate node instruction results.

The instructionResults property is an array of node instruction objects representing the instruction execution results. There should be one object for each instruction generated by the Request Transform, and in the same order. Each object supports the following properties:

Property Type Description
nodeId Number The node ID.
state String A node instruction state type value, e.g. Completed, Declined.
resultParameters Object Arbitrary instruction execution result data.

For example:

{
  "contentType": "application/json",
  "data": "{\"groupId\":\"abc-123\"}",
  "parameters": {
    "foo": "bar"
  },
  "instructionResults": [
    {
      "nodeId": "179",
      "state": "Completed",
      "resultParameters": {
        "datum": [
          {
            "sourceId": "test/1",
            "watts": 123,
            "voltage": 240
          },
          {
            "sourceId": "test/2",
            "watts": 234,
            "voltage": 241
          }
        ]
      }
    }
  ]
}

The response will be a Transform Output object with the following properties:

Property Type Description
instructions Array<Object> A list of the successfully converted node instruction objects.
message String An error message, if an error occurred.
response String The conversion output of the endpoint's configured Response Transform. The value will be Base64 encoded if the Response Transform produces binary data.
transformOutput String Intermediate output of the transform service, if the service generates one (for example the JSON output of the XSLT Request Transform Service).

An example response looks like:

{
  "success": true,
  "data": {
    "instructions": [
      {
        "topic": "LatestDatum",
        "state": "Completed",
        "parameters": [
          {
            "name": "sourceIds",
            "value": "test/1,test/2"
          }
        ],
        "nodeId": 179,
        "resultParameters": {
          "datum": [
            {
              "sourceId": "test/1",
              "watts": 123,
              "voltage": 240
            },
            {
              "sourceId": "test/2",
              "watts": 234,
              "voltage": 241
            }
          ]
        }
      }
    ],
    "response": "{\"total-power\":357}",
    "transformOutput": "{\"topic\":\"LatestDatum\",\"params\":{\"sourceIds\":\"abc-123\"}}"
  }
}

Endpoint Authorizations

Endpoint Authorization entities associate a Credential with an Endpoint, defining the credentials allowed to post data to the endpoint. Authorizations for any number of unique credentials can be a created for a given endpoint. A given credential can be associated with any number of endpoints.

Endpoint Authorization list

This method returns a list of Endpoint Authorization entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/inin/endpoints/auths

The request body accepts the following search filter query parameters:

Property Type Description
endpointId Number The ID of an endpoint to match.
endpointIds Array<Number> A comma-delimited list of endpoint IDs to match (logical OR).
credentialId Number The ID of a credential to match.
credentialIds Array<Number> A comma-delimited list of credential IDs to match (logical OR).
enabled Boolean The desired enabled state to match.
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Endpoint Authorization entity objects. See the Endpoint Authorization view response for details.

Endpoint Authorization view

This method returns an Endpoint Authorization entity.

GET /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/auths/{credentialId}
endpointId The endpoint ID of the Endpoint Authorization to view.
credentialId The credential ID of the Endpoint Authorization to view.

Endpoint Authorization view response

The response will be an Endpoint Authorization entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
endpointId String The ID of the associated endpoint entity.
credentialId Number The ID of the associated credential entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator. Only enabled entities will be considered during authorization.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "endpointId": "d4f3d589-31fd-4005-b780-b0593f943910",
    "credentialId": 1,
    "created": "2024-02-23 05:36:03.447153Z",
    "modified": "2024-02-26 06:51:19.787894Z",
    "enabled": true
  }
}

Endpoint Authorization save

This method creates or updates an existing Endpoint Authorization entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/auths/{credentialId}
endpointId The endpoint ID of the Endpoint Authorization to update.
credentialId The credential ID of the Endpoint Authorization to update.

The request body accepts an Endpoint Authorization JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.

For example:

{"enabled":true}

Endpoint Authorization delete

This method deletes an Endpoint Authorization entity. All Endpoint Authorization Authorization entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/auths/{credentialId}
endpointId The endpoint ID of the Endpoint Authorization to delete.
credentialId The credential ID of the Endpoint Authorization to delete.

Endpoint Authorization update enabled

This method updates the enabled status of an Endpoint Authorization entity.

POST /solaruser/api/v1/sec/user/inin/endpoints/{endpointId}/auths/{credentialId}/enabled/{enabled}
endpointId The endpoint ID of the Endpoint Authorization to update.
credentialId The credential ID of the Endpoint Authorization to update.
enabled The desired enabled state to set.

Request Transform Service list

This method will list the request transform services supported by SolarNetwork.

GET /solaruser/api/v1/sec/user/inin/services/request-transform

SolarNetwork supports the following transform services:

Service Description
XSLT Convert input messages using an XSLT stylesheet.

Response Transform Service list

This method will list the response transform services supported by SolarNetwork.

GET /solaruser/api/v1/sec/user/inin/services/response-transform

SolarNetwork supports the following transform services:

Service Description
XSLT Convert instruction results to output messages using an XSLT stylesheet.
Add a custom footer
Clone this wiki locally