Skip to content

SolarUser Datum Expire API

Jump to bottom Edit New page
Matt Magoffin edited this page Mar 23, 2022 · 1 revision

The SolarUser Datum Expire API provides methods to manage datum expiration policies and submit ad hoc datum delete tasks. Expiration policies are applied continuously by SolarNetwork, for all active configurations. Ad-hoc delete tasks are executed just once, after submitting one.

All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

Endpoints

Verb Endpoint Description
GET /user/expire/configs List previously submitted expire configurations.
POST /user/expire/configs/data Store an expiration data configuration.
DELETE /user/expire/configs/data/{id} Delete an expiration data configuration.
GET /user/expire/configs/data/{id}/preview Preview the impact of applying an expiration data configuration.
POST /user/expire/datum-delete Preview the impact of an ad hoc delete datum request.
POST /user/expire/datum-delete/confirm Submit a delete datum request.
GET /user/expire/datum-delete/jobs List datum delete jobs.
GET /user/expire/datum-delete/jobs/{id} View information about a specific datum delete job.
GET /user/expire/services/aggregation List the available aggregation types.

Localized responses

Many endpoints return localized messages. The locale of the response is determined by the Accept-Language HTTP header passed on the request. If not provided, the default locale of the SolarNetwork service will be used.

Expiration data configuration object

A data configuration object represents the criteria for what data should be deleted. Each object contains the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork.
created string The date the configuration was submitted, in YYYY-MM-dd HH:mm:ss.SSS'Z' format, in the UTC time zone.
serviceIdentifier string A unique identifier for the type of data configuration. Will always be net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService.
userId number The ID of the user that owns the configuration.
name string A user-assigned name for the configuration.
active boolean true when this configuration is active.
expireDays number The minimum number of days old datum must be to be deleted.
datumFilter object An expiration datum filter object to select which datum to delete.

An example expiration data object looks like the following:

{
  "id": 6,
  "created": "2018-07-11 04:01:41.859Z",
  "userId": 1,
  "name": "Raw power after 2y",
  "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
  "active": false,
  "expireDays": 730,
  "datumFilter": {
    "aggregation": "None",
    "nodeIds": 123,
    "sourceIds": ["/power/*"]
  }
}

Expiration datum filter object

This object represents the criteria to choose from which datum streams to delete. Each object contains the following properties:

Property Type Description
aggregationKey string The largest aggregation to include in the delete task. Matching datum with lower aggregations, up to and including this aggregation, will be deleted.
nodeIds array<number> The list of node IDs to match.
sourceIds array<string> The list of source IDs to match. Wildcard patterns are supported.

An example expiration data object looks like the following:

{
  "aggregationKey": "0",
  "nodeIds": 123,
  "sourceIds": ["/power/*"]
}

List aggregation types

List the available aggregation types for configuring in an expiration datum filter object.

GET /solaruser/api/v1/sec/user/expire/services/aggregation

List aggregation types response

The response is a list of aggregation localized service objects. An example looks like this:

{
  "success": true,
  "data": [
    {
      "id": "0",
      "locale": "en-NZ",
      "localizedDescription": "None",
      "localizedName": "None"
    },
    {
      "id": "h",
      "locale": "en-NZ",
      "localizedDescription": "Hour",
      "localizedName": "Hour"
    },
    {
      "id": "d",
      "locale": "en-NZ",
      "localizedDescription": "Day",
      "localizedName": "Day"
    },
    {
      "id": "M",
      "locale": "en-NZ",
      "localizedDescription": "Month",
      "localizedName": "Month"
    }
  ]
}

List expire configurations

List all available expire configurations.

GET /solaruser/api/v1/sec/user/expire/configs

List expire configurations response

The response contains a list of expire configuration objects. Each configuration has the following properties:

Property Type Description
dataConfigs array<object> The list of available expiration data configuration objects.

An example response looks like:

{
  "success": true,
  "data": {
    "dataConfigs": [
      {
        "id": 6,
        "created": "2018-07-11 04:01:41.859Z",
        "userId": 1,
        "name": "All raw after 2y",
        "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
        "active": false,
        "expireDays": 730,
        "datumFilter": {
          "aggregation": "None"
        }
      },
      {
        "id": 5,
        "created": "2018-07-11 01:49:11.335Z",
        "userId": 1,
        "name": "Fleeting",
        "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
        "active": false,
        "expireDays": 7,
        "datumFilter": {
          "sourceIds": [
            "/power/switch/*"
          ],
          "aggregation": "Month"
        }
      }
    ]
  }
}

Store expire data configuration

Create or update an expiration data configuration to define a datum expiration policy. The request body must be a full JSON expiration data configuration object.

POST /solaruser/api/v1/sec/user/expire/configs/data

Delete expire data configuration

Delete an expiration data configuration.

DELETE /solaruser/api/v1/sec/user/expire/configs/data/{id}
id The unique ID of the configuration to delete.

Preview expire data

Preview the effects of applying an expiration data configuration. This will show you a summary of how many datum would be deleted if the configuration were applied.

GET /solaruser/api/v1/sec/user/expire/configs/data/{id}/preview
id The unique ID of the configuration to preview.

Preview expire data response

The response is a summary object with the following properties:

Property Type Description
date string The date the preview was executed, in YYYY-MM-dd HH:mm:ss.SSS'Z' format, in the UTC time zone.
datumTotalCount number The total number of datum, across all aggregation types, that would be deleted.
datumCount number The number of raw datum that would be deleted.
datumHourlyCount number The number of hourly aggregate datum that would be deleted.
datumDailyCount number The number of daily aggregate datum that would be deleted.
datumCMonthlyount number The number of monthly aggregate datum that would be deleted.

An example response looks like:

{
  "success": true,
  "data": {
    "date": "2022-03-21 11:00:00Z",
    "datumTotalCount": 1071,
    "datumCount": 819,
    "datumHourlyCount": 188,
    "datumDailyCount": 52,
    "datumMonthlyCount": 12
  }
}

Delete datum preview

This method allows you to find out how many datum would be deleted if datum matching the submitted criteria were deleted.

⚠️ Note that unless you include a date range in the given filter, all datum matching the given node/source IDs will be deleted. Specify a date range with the startDate/endDate or localStartDate/localEndDate properties to limit the date range.

POST /solaruser/api/v1/sec/user/expire/datum-delete
aggregationKey The largest aggregation to include in the delete task. Matching datum with lower aggregations, up to and including this aggregation, will be deleted.
nodeIds The list of node IDs to match.
sourceIds The list of source IDs to match. Wildcard patterns are supported.
localStartDate An inclusive minimum date of datum to delete, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate An exclusive maximum date of datum to delete, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
startDate An inclusive minimum date of datum to delete, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate An exclusive maximum date of datum to delete, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.

Notes:

  • Use either the local*Date or *Date parameters; do not mix the two styles. For example, providing localStartDate and endDate parameters together is not supported.

Delete datum preview response

The response is the same as in the preview expire data response method. An example response looks like this:

{
  "success": true,
  "data": {
    "date": "2022-03-21 11:00:00Z",
    "datumTotalCount": 1071,
    "datumCount": 819,
    "datumHourlyCount": 188,
    "datumDailyCount": 52,
    "datumMonthlyCount": 12
  }
}

Delete datum

This method allows you to deleted a range of datum matching the submitted criteria. The request takes the same parameters as the Delete datum preview method. The data is not deleted immediately. Instead, a delete job is scheduled and will be performed at some point in the future. You can view the status of jobs using the Delete datum jobs list method.

POST /solaruser/api/v1/sec/user/expire/datum-delete/confirm

Delete datum response

The response object is a delete datum job object, with the following properties:

Property Type Description
id string The unique ID of the delete job.
jobState string The state of the job, one of Queued, Claimed, Executing, Completed.
userId number The ID of the user that submitted the job.
configuration object The delete filter criteria submitted with the job.
percentComplete number The percent complete the job is, from 0 - 1.
submitDate number A millisecond epoch date when the delete job was created.
startedDate number A millisecond epoch date when the delete job started, or 0 if not started yet.
completionDate number A millisecond epoch date when the delete job completed, or 0 if not complete.
resultCount number A millisecond epoch date when the delete job completed, or 0 if not complete.
success number true if the delete job completed successfully.
jobDuration number The number of milliseconds the job took to complete.

An example response looks like this:

{
  "success": true,
  "data": {
    "id": "7d8a3ad7-0c2c-44ab-b708-6555296f4af3"
    "jobState": "Queued",
    "userId": 147,
    "configuration": {
      "nodeIds": [1,2,3]
      "sourceIds": ["/power/1","/power/2"],
      "aggregation": "None",
      "localStartDate": "2019-01-22 00:50:00",
      "localEndDate": "2020-01-25 04:00:00"
    },
    "percentComplete": 0.0,
    "submitDate": 1648002593507,
    "startedDate": 0,
    "completionDate": 0,
    "resultCount": 0,
    "success": false,
    "jobDuration": 0,
  }
}

Delete datum jobs list

This method allows you to deleted a range of datum matching the submitted criteria. The request takes the same parameters as the Delete datum preview method. The data is not deleted immediately. Instead, a delete job is scheduled and will be performed at some point in the future. You can view the status of jobs using the Delete datum jobs list method.

GET /solaruser/api/v1/sec/user/expire/datum-delete/jobs
states Comma-delimited list of job states to limit the results to. Possible job states include: Queued, Claimed, Executing, Completed.

Delete datum jobs list response

The response contains a list of delete datum job objects. See the Delete datum response for more information.

Delete datum job view

This method allows you to view the status of a specific job.

GET /solaruser/api/v1/sec/user/expire/datum-delete/jobs/{id}
id The ID of the job to view.

The response will be a delete datum job object. See the Delete datum response for more information.

Add a custom footer
Clone this wiki locally