Skip to content

SolarUser DIN API

Jump to bottom Edit New page
Matt Magoffin edited this page Feb 27, 2024 · 13 revisions

The SolarUser Datum Input Endpoint API (DIN) provides methods to manage HTTP integration endpoint entities within SolarNetwork, that allow arbitrary measurement data to be ingested as a datum stream. 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 DIN support in SolarNetwork see the Datum Input Endpoint guide.

Endpoints

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

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 /transforms Create transform
GET /transforms List transforms
GET /transforms/{transformId} View transform
PUT /transforms/{transformId} Update transform
DELETE /transforms/{transformId} Delete transform
POST /transforms/{transformId}/enabled/{enabled} Update transform enabled status
POST /transforms/{transformId}/preview Preview transform conversion
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
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

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/din/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.

For example:

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

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/din/credentials/1

Credential list

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

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

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

Property Type Description
credentialId Number The ID of a credential to match.
credentialIds Array<Number> A 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/din/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.

⚠️ 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"
  }
}

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/din/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/din/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/din/credentials/{credentialId}/enabled/{enabled}
credentialId The ID of the Credential to update.
enabled The desired enabled state to set.

Transforms

Transform entities define raw measurement data conversions, by configuring a Transform Service along with any settings supported by that service. A Transform entity can associated with any number of Endpoints.

Transform create

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

POST /solaruser/api/v1/sec/user/din/transforms

The request body accepts a 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 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/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 Transform entity object that provides the ID assigned to the new Transform. See 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/din/transforms/1

Transform list

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

GET /solaruser/api/v1/sec/user/din/transforms

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

Property Type Description
transformId Number The ID of a transform to match.
transformIds Array<Number> A 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 Transform view response for details.

Transform view

This method returns a Transform entity.

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

Transform view response

The response will be a 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 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/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>"
    }
  }
}

Transform update

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

PUT /solaruser/api/v1/sec/user/din/transforms/{transformId}
transformId The ID of the Transform to update.

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

Transform delete

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

DELETE /solaruser/api/v1/sec/user/din/transforms/{transformId}
transformId The ID of the Transform to delete.

Transform update enabled

This method updates the enabled status of a Transform entity.

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

Transform preview

This method allows you to simulate the data conversion process using a given Transform entity.

POST /solaruser/api/v1/sec/user/din/transforms/{transformId}/preview
transformId The ID of the Transform to execute.

The request body accepts either JSON or XML content, and must be in a form expected by the Transform Service configured on the specified Transform entity.

The body can be compressed using gzip if you include a Content-Encoding: gzip HTTP header.

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

Property Type Description
datum Array<Object> A list of the successfully converted native SolarNetwork datum.
transformOutput String Intermediate output of the transform service, if the service generates one (for example the JSON output of the XSLT Transform Service).
message String An error message, if an error occurred.

An example response for a preview using the XSLT Transform Service looks like:

{
  "success": true,
  "data": {
    "datum": [
      {
        "created": "2024-02-22 12:00:00Z",
        "sourceId": "test/1",
        "i": {
          "foo": 123
        }
      },
      {
        "created": "2024-02-22 12:01:00Z",
        "nodeId": 124,
        "sourceId": "test/2",
        "i": {
          "bim": 234
        }
      }
    ],
    "transformOutput": "[{\"created\":\"2024-02-22T12:00:00Z\",\"sourceId\":\"test/1\",\"i\":{\"foo\":123}},{\"created\":\"2024-02-22T12:01:00Z\",\"nodeId\":124,\"sourceId\":\"test/2\",\"i\":{\"bim\":234}}]"
  }
}

Another example showing an error result looks like:

{
  "success": true,
  "data": {
    "transformOutput": "",
    "message": "External resources are not allowed (common-templates.xsl)."
  }
}

Endpoints

Endpoint entities define a unique data input URL, with an associated Transform to use for converting the input measurement data to SolarNetwork native datum, and node and source ID values to assign to the converted datum.

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/din/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.
nodeId Number The node ID to assign to converted datum. Omit if the transform itself generates the node ID.
sourceId Number The source ID to assign to converted datum. Omit if the transform itself generates the node ID.
transformId Number The ID of the Transform entity to use for converting the input data.

For example:

{"name":"Meter XML","nodeId":1,"sourceId":"meter/1","transformId":1,"enabled":true}

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/din/endpoints/1

Endpoint list

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

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

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

Property Type Description
endpointId Number The ID of an endpoint to match.
endpointIds Array<Number> A 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/din/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.
nodeId Number The node ID to assign to converted datum. Omit if the transform itself generates the node ID.
sourceId Number The source ID to assign to converted datum. Omit if the transform itself generates the node ID.
transformId Number The ID of the Transform entity to use for converting the input data.

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",
    "nodeId": 1,
    "sourceId": "meter/1",
    "transformId": 1
  }
}

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/din/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/din/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/din/endpoints/{endpointId}/enabled/{enabled}
endpointId The ID of the Endpoint to update.
enabled The desired enabled state to set.

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/din/endpoints/auths

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

Property Type Description
endpointId Number The ID of an endpoint to match.
endpointIds Array<Number> A list of endpoint IDs to match (logical OR).
credentialId Number The ID of a credential to match.
credentialIds Array<Number> A 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/din/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/din/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/din/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/din/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.
Add a custom footer
Clone this wiki locally