Skip to content

SolarUser OSCP API

Jump to bottom Edit New page
Matt Magoffin edited this page Oct 11, 2022 · 9 revisions

The SolarUser OSCP API provides methods to manage Open Smart Charging Protocol (OSCP) entities within SolarNetwork, which provides an implementation of the OSCP Flexibility Provider (FP) system. 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.

For general information about OSCP support in SolarNetwork see the OSCP guide.

Endpoints

Verb Endpoint Description
POST /user/oscp/assets Create an Asset
GET /user/oscp/assets/{assetId} View an Asset
PUT /user/oscp/assets/{assetId} Update an Asset
DELETE /user/oscp/assets/{assetId} Delete an Asset
GET /user/oscp/capacity-groups List Capacity Groups
POST /user/oscp/capacity-groups Create a Capacity Group
GET /user/oscp/capacity-groups/{groupId} View a Capacity Group
PUT /user/oscp/capacity-groups/{groupId} Update a Capacity Group
DELETE /user/oscp/capacity-groups/{groupId} Delete a Capacity Group
GET /user/oscp/capacity-groups/{groupId}/assets List a Capacity Group's assets
GET /user/oscp/capacity-groups/{groupId}/settings View a Capacity Group settings
PUT /user/oscp/capacity-groups/{groupId}/settings Update a Capacity Group settings
DELETE /user/oscp/capacity-groups/{groupId}/settings Delete a Capacity Group settings
GET /user/oscp/capacity-groups/settings List Capacity Group settings.
GET /user/oscp/capacity-optimizers List Capacity Optimizers
POST /user/oscp/capacity-optimizers Create a Capacity Optimizer
GET /user/oscp/capacity-optimizers/{optimizerId} View a Capacity Optimizer
PUT /user/oscp/capacity-optimizers/{optimizerId} Update a Capacity Optimizer
DELETE /user/oscp/capacity-optimizers/{optimizerId} Delete a Capacity Optimizer
GET /user/oscp/capacity-providers List Capacity Providers
POST /user/oscp/capacity-providers Create a Capacity Provider
PUT /user/oscp/capacity-providers/{providerId} Update a Capacity Provider
GET /user/oscp/capacity-providers/{providerId} View a Capacity Provider
DELETE /user/oscp/capacity-providers/{providerId} Delete a Capacity Provider
GET /user/oscp/settings View user settings
PUT /user/oscp/settings Update user settings
DELETE /user/oscp/settings Delete user settings

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.

OAuth client service properties

The Capacity Providers and Capacity Optimizer entities can be configured with OAuth credentials so SolarNetwork authenticates to those systems using the OAuth client credentials authentication flow. To enable this mode, the entity in question must be configured with the following service properties (in the serviceProps property), which should be provided by the system's organisation:

Property Type Description
oauth-token-url string The URL to the system's OAuth token endpoint, e.g. https://auth.example.com/oauth2/token.
oauth-client-id string The OAuth client ID to use, e.g. e0diodjdl3ou3093j3jlkl.
oauth-client-secret string The OAuth client secret to use, e.g. dlidfj4894hjdfldfhjtgh3903.

⚠️ Note that the client secret will not be returned by the SolarNetwork API. You can reset the password at any time by simply updating the service properties with the new settings (all service properties must be provided each time).

OAuth Flexibility Provider configuration

To enable OAuth authentication for CP and CO systems to authenticate to SolarNetwork (instead of the OSCP standard token-based authentication) then you must reach out to your SolarNetwork account manager for the OAuth credentials to be created and configured for the system(s) in question. The system entity must be created first) (i.e. via Capacity Providers create or Capacity Optimizers create) before the OAuth credentials can be configured.

Capacity Groups

Capacity Group entities pair a single Capacity Provider entity with a single Capacity Optimizer entity and has the settings that define how the group operates, such as the measurement reporting frequency. A group also defines a set of Asset entities.

Capacity Groups create

Create a Capacity Group entity, for integrating with an external OSCP Capacity Group system. Use the Capacity Groups list endpoint to view all saved groups. Once a group is created you can add Asset entities to the group.

POST /solaruser/api/v1/sec/user/oscp/capacity-groups

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
name string A friendly display name for the group, e.g. My Group.
identifier string A unique identifier for the group, which will be used in OSCP messages, e.g. my-group.
capacityProviderId number The configId of the Capacity Provider entity to accept capacity forecasts from and report measurements to.
capacityProviderMeasurementPeriod string A Measurement Period value that defines the frequency at which measurements should be reported to the CP.
capacityOptimizerId number The configId of the Capacity Optimizer entity to forward capacity forecasts to.
capacityOptimizerMeasurementPeriod string A Measurement Period value that defines the frequency at which measurements should be reported to the CO.
enabled boolean true if the the group can be used, false otherwise.

For example:

{
  "name"                               : "My Group",
  "identifier"                         : "my-group",
  "capacityProviderId"                 : 1,
  "capacityProviderMeasurementPeriod"  : "FifteenMinute",
  "capacityOptimizerId"                : 2,
  "capacityOptimizerMeasurementPeriod" : "FiveMinute",
  "enabled"                            : true
}

Capacity Groups create response

The response will be a Capacity Group entity object, including a unique assigned configId value.

For example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-09-08 22:54:31.746647Z",
    "modified": "2022-09-08 22:54:31.746647Z",
    "name": "My Group",
    "enabled": true,
    "identifier": "my-group",
    "capacityProviderMeasurementPeriod": "FifteenMinute",
    "capacityOptimizerMeasurementPeriod": "FiveMinute",
    "capacityProviderId": 1,
    "capacityOptimizerId": 2
  }
}

Capacity Groups update

Update a single Capacity Group entity.

PUT /solaruser/api/v1/sec/user/oscp/capacity-groups/{groupId}
groupId The configId of the Capacity Group to update.

⚠️ Note a complete Capacity Group configuration must be given, as it will replace the existing settings for the entity.

Capacity Groups view

View a single Capacity Group entity.

GET /solaruser/api/v1/sec/user/oscp/capacity-groups/{groupId}
groupId The configId of the Capacity Group to view.

The response is a Capacity Group entity, for example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-09-08 22:54:31.746647Z",
    "modified": "2022-09-08 22:54:31.746647Z",
    "name": "My Group",
    "enabled": true,
    "identifier": "my-group",
    "capacityProviderMeasurementPeriod": "FifteenMinute",
    "capacityOptimizerMeasurementPeriod": "FiveMinute",
    "capacityProviderId": 1,
    "capacityOptimizerId": 2
  }
}

Capacity Groups delete

Delete a single Capacity Group.

DELETE /solaruser/api/v1/sec/user/oscp/capacity-groups/{groupId}
groupId The configId of the Capacity Group to delete.

The response is empty.

Capacity Groups list

List the available Capacity Group entities in your account.

GET /solaruser/api/v1/sec/user/oscp/capacity-groups

The response contains a list of Capacity Group entities.

Capacity Groups Assets list

List the assets in a Capacity Group.

DELETE /solaruser/api/v1/sec/user/oscp/capacity-groups/{groupId}/assets
groupId The configId of the Capacity Group to list the assets for.

The response is a list of asset entities, see Assets view for more information.

Assets

Asset entities contain the settings necessary for SolarNetwork to provide measurements to external Capacity Provider and Optimizer systems, such as the node and source ID of the datum stream(s) that contain the measurement data.

Assets create

Create an Asset entity, for integrating with an external OSCP Asset system. Use the Assets list endpoint to view all saved optimizers.

POST /solaruser/api/v1/sec/user/oscp/assets

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
name string A friendly display name for the asset, e.g. My Charger.
capacityGroupId string The configId of the Capacity Group to add the asset to.
identifier string A unique identifier to use in OSCP messages.
enabled boolean true if the the asset can be used, false otherwise.
audience string The system the asset should have measurements reported to. Can be either CapacityProvider or CapacityOptimizer.
nodeId number The node ID of the datum stream to read measurements from.
sourceId string The source ID of the datum stream to read measurements from.
category string An Asset Category enumeration value.
phase string A Phase enumeration value.
instantaneous object The instantaneous measurement settings, if appropriate.
energy object The energy measurement settings, if appropriate.

The instantaneous object supports the following properties:

Property Type Description
propertyNames array<string> A list of datum stream instantaneous property names to measure.
unit string The Measurement Unit of the property values.
multiplier number An optional value to multiply the raw measurement values by to convert them into unit, if not already in the given measurement unit.
statisticType string The Statistic Type to extract from the property values.

The energy object supports all of the given instantaneous properties, and the following additional properties:

Property Type Description
type string The Energy Type of the asset.
direction string The Energy Direction of the asset.

For example:

{
  "name"            : "Charger 1",
  "capacityGroupId" : 1,
  "identifier"      : "XYZ.ABC.123",
  "audience"        : "CapacityProvider",
  "enabled"         : true,
  "nodeId"          : 123,
  "sourceId"        : "charger/1",
  "category"        : "Charging",
  "phase"           : "All",
  "instantaneous" : {
    "propertyNames" : ["watts"],
    "unit"          : "W",
    "statisticType" : "Maximum"
  },
  "energy" : {
    "propertyNames" : ["wattHours"],
    "unit"          : "Wh",
    "statisticType" : "Difference",
    "type"          : "Total",
    "direction"     : "Import"
  }
}

Assets create response

The response will be a Asset entity object, including a unique assigned configId value.

⚠️ Note the token value is only returned in this response. It will not be shown in any other response. You must store the value in a safe place and securely provide it to the Asset organisation. If OAuth authentication is to be configured then the token value can be ignored.

For example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-09-08 23:15:41.158037Z",
    "modified": "2022-09-08 23:15:41.158037Z",
    "name": "Charger 1",
    "enabled": true,
    "capacityGroupId": 1,
    "identifier": "XYZ.ABC.123",
    "audience": "CapacityProvider",
    "nodeId": 123,
    "sourceId": "charger/1",
    "category": "Charging",
    "phase": "All",
    "instantaneous": {
      "propertyNames": ["watts"],
      "unit": "W",
      "statisticType": "Maximum"
    },
    "energy": {
      "propertyNames": ["wattHours"],
      "unit": "Wh",
      "statisticType": "Difference",
      "type": "Total",
      "direction": "Import"
    }
  }
}

Assets update

Update a single Asset entity.

PUT /solaruser/api/v1/sec/user/oscp/assets/{assetId}
assetId The configId of the Asset to update.

⚠️ Note a complete Asset configuration must be given, as it will replace the existing settings for the entity.

Assets view

View a single Asset entity.

GET /solaruser/api/v1/sec/user/oscp/assets/{assetId}
assetId The configId of the Asset to view.

The response is a Asset entity, for example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-09-08 23:15:41.158037Z",
    "modified": "2022-09-08 23:15:41.158037Z",
    "name": "Charger 1",
    "enabled": true,
    "capacityGroupId": 1,
    "identifier": "XYZ.ABC.123",
    "audience": "CapacityProvider",
    "nodeId": 123,
    "sourceId": "charger/1",
    "category": "Charging",
    "phase": "All",
    "instantaneous": {
      "propertyNames": ["watts"],
      "unit": "W",
      "statisticType": "Maximum"
    },
    "energy": {
      "propertyNames": ["wattHours"],
      "unit": "Wh",
      "statisticType": "Difference",
      "type": "Total",
      "direction": "Import"
    }
  }
}

Assets delete

Delete a single Asset.

DELETE /solaruser/api/v1/sec/user/oscp/assets/{assetId}
assetId The configId of the Asset to delete.

The response is empty.

Capacity Optimizers

Capacity Optimizer entities contain the settings necessary for SolarNetwork to communiate with a external Capacity Optimizer systems, such as the URL and credentials to use.

Capacity Optimizers create

Create a Capacity Optimizer entity, for integrating with an external OSCP Capacity Optimizer system. Use the Capacity Optimizers list endpoint to view all saved optimizers.

POST /solaruser/api/v1/sec/user/oscp/capacity-optimizers

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
name string A friendly display name for the optimizer, e.g. ACME Lines Co.
baseUrl string The base absolute URL to the optimizer's OSCP API, e.g. https://oscp.acme.example.com/oscp/cp/2.0.
oscpVersion string The expected OSCP version to use, e.g. 2.0.
enabled boolean true if the the optimizer system can be used, false otherwise.
serviceProps object An optional set of settings. Required for OAuth authentication, see OAuth client service properties for more information.

For example:

{
  "name"        : "Optimizer Co.",
  "baseUrl"     : "https://oscp.example.com/oscp/co/2.0",
  "oscpVersion" : "2.0",
  "enabled"     : true,
  "serviceProps" : {
    "oauth-token-url"     : "https://auth.example.com/oauth2/token",
    "oauth-client-id"     : "client-123",
    "oauth-client-secret" : "Secret.123"
  }
}

Capacity Optimizers create response

The response will be a Capacity Optimizer entity object, including a unique assigned configId value, and an assigned token value to give to the Capacity Optimizer for authenticating to SolarNetwork. The flexibilityProviderId will also be returned, which is required for assigning the optimizer to a Capacity Group.

⚠️ Note the token value is only returned in this response. It will not be shown in any other response. You must store the value in a safe place and securely provide it to the Capacity Optimizer organisation. If OAuth authentication is to be configured then the token value can be ignored.

For example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-08-30 01:42:39.929692Z",
    "modified": "2022-08-30 01:42:39.929692Z",
    "enabled": true,
    "name": "Optimizer Co.",
    "token": "EL+47CQHeIXjoNiGmUOnDa1gpEf9+WD50R9ax4hOkBbc2S2rmPNyYoSvcwWM1oAO",
    "baseUrl": "https://oscp.example.com/oscp/co/2.0",
    "flexibilityProviderId": 2,
    "registrationStatus": "Pending",
    "settings": {},
    "serviceProps": {
      "oauth-client-id": "client-123",
      "oauth-token-url": "https://auth.example.com/oauth2/token"
    }
  }
}

Capacity Optimizers update

Update a single Capacity Optimizer entity.

PUT /solaruser/api/v1/sec/user/oscp/capacity-optimizers/{optimizerId}
optimizerId The configId of the Capacity Optimizer to update.

⚠️ Note a complete Capacity Optimizer configuration must be given, as it will replace the existing settings for the entity.

Capacity Optimizers view

View a single Capacity Optimizer entity.

GET /solaruser/api/v1/sec/user/oscp/capacity-optimizers/{optimizerId}
optimizerId The configId of the Capacity Optimizer to view.

The response is a Capacity Optimizer entity, for example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-08-30 01:42:39.929692Z",
    "modified": "2022-08-30 01:42:39.929692Z",
    "enabled": true,
    "name": "Lines Co.",
    "baseUrl": "https://oscp.example.com/oscp/co/2.0",
    "flexibilityProviderId": 2,
    "registrationStatus": "Registered",
    "settings": {
      "heartbeatSeconds": 60,
      "measurementStyles": [
        "Continuous"
      ]
    },
    "serviceProps": {
      "oauth-client-id": "client-123",
      "oauth-token-url": "https://auth.example.com/oauth2/token"
    }
  }
}

Capacity Optimizers delete

Delete a single Capacity Optimizer.

DELETE /solaruser/api/v1/sec/user/oscp/capacity-optimizers/{optimizerId}
optimizerId The configId of the Capacity Optimizer to delete.

The response is empty.

Capacity Optimizers list

List the available Capacity Optimizer entities in your account.

GET /solaruser/api/v1/sec/user/oscp/capacity-optimizers

The response contains a list of Capacity Optimizer entities.

Capacity Providers

Capacity Provider entities contain the settings necessary for SolarNetwork to communiate with a external Capacity Provider systems, such as the URL and credentials to use.

Capacity Providers create

Create a Capacity Provider entity, for integrating with an external OSCP Capacity Provider system. Use the Capacity Providers list endpoint to view all saved providers.

POST /solaruser/api/v1/sec/user/oscp/capacity-providers

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
name string A friendly display name for the provider, e.g. ACME Lines Co.
baseUrl string The base absolute URL to the provider's OSCP API, e.g. https://oscp.acme.example.com/oscp/cp/2.0.
oscpVersion string The expected OSCP version to use, e.g. 2.0.
enabled boolean true if the the provider system can be used, false otherwise.
serviceProps object An optional set of settings. Required for OAuth authentication, see OAuth client service properties for more information.

For example:

{
  "name"        : "Lines Co.",
  "baseUrl"     : "https://oscp.example.com/oscp/cp/2.0",
  "oscpVersion" : "2.0",
  "enabled"     : true,
  "serviceProps" : {
    "oauth-token-url"     : "https://auth.example.com/oauth2/token",
    "oauth-client-id"     : "client-123",
    "oauth-client-secret" : "Secret.123"
  }
}

Capacity Providers create response

The response will be a Capacity Provider entity object, including a unique assigned configId value, and an assigned token value to give to the Capacity Provider for authenticating to SolarNetwork. The flexibilityProviderId will also be returned, which is required for assigning the provider to a Capacity Group.

⚠️ Note the token value is only returned in this response. It will not be shown in any other response. You must store the value in a safe place and securely provide it to the Capacity Provider organisation. If OAuth authentication is to be configured then the token value can be ignored.

For example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-08-30 01:42:39.929692Z",
    "modified": "2022-08-30 01:42:39.929692Z",
    "enabled": true,
    "name": "Lines Co.",
    "token": "EL+47CQHeIXjoNiGmUOnDa1gpEf9+WD50R9ax4hOkBbc2S2rmPNyYoSvcwWM1oAO",
    "baseUrl": "https://oscp.example.com/oscp/cp/2.0",
    "flexibilityProviderId": 2,
    "registrationStatus": "Pending",
    "settings": {},
    "serviceProps": {
      "oauth-client-id": "client-123",
      "oauth-token-url": "https://auth.example.com/oauth2/token"
    }
  }
}

Capacity Providers update

Update a single Capacity Provider entity.

PUT /solaruser/api/v1/sec/user/oscp/capacity-providers/{providerId}
providerId The configId of the Capacity Provider to update.

⚠️ Note a complete Capacity Provider configuration must be given, as it will replace the existing settings for the entity.

Capacity Providers view

View a single Capacity Provider entity.

GET /solaruser/api/v1/sec/user/oscp/capacity-providers/{providerId}
providerId The configId of the Capacity Provider to view.

The response is a Capacity Provider entity, for example:

{
  "success": true,
  "data": {
    "userId": 1,
    "configId": 1,
    "created": "2022-08-30 01:42:39.929692Z",
    "modified": "2022-08-30 01:42:39.929692Z",
    "enabled": true,
    "name": "Lines Co.",
    "baseUrl": "https://oscp.example.com/oscp/cp/2.0",
    "flexibilityProviderId": 2,
    "registrationStatus": "Registered",
    "settings": {
      "heartbeatSeconds": 60,
      "measurementStyles": [
        "Continuous"
      ]
    },
    "serviceProps": {
      "oauth-client-id": "client-123",
      "oauth-token-url": "https://auth.example.com/oauth2/token"
    }
  }
}

Capacity Providers delete

Delete a single Capacity Provider.

DELETE /solaruser/api/v1/sec/user/oscp/capacity-providers/{providerId}
providerId The configId of the Capacity Provider to delete.

The response is empty.

Capacity Providers list

List the available Capacity Provider entities in your account.

GET /solaruser/api/v1/sec/user/oscp/capacity-providers

The response contains a list of Capacity Provider entities.

Add a custom footer

Clone this wiki locally