Service Properties

Service Properties

Some entities in the SolarNetwork API include a serviceProperties property that is an arbitrary map data structure using string keys and arbitrary values. In JSON this is expressed as a JSON object, for example:

{
	"apiKey": "{SSHA-256}aQrTEQH1rQoe...",
	"sourceIdMap": {
		"/123789/inv/98765": "/INV/1"
	},
	"virtualSourceIds": [
		"/GEN/1"
	]
}

Usually only specific keys in this mapping are supported by the associated entity type, however SolarNetwork does not usually restrict what entries are included in the mapping.

Merge operation

Some APIs offer a PATCH endpoint to merge changes into an entity's service properties. This is a convenient way to add or update the service properties, without having to post the entire object. The body of the PATCH request is a JSON object with just the properties you need to add or change.

These PATCH endpoints will support a mode query parameter that can alter the way nested objects and lists within the service properties object are merged.

Simple merge mode

The default merge mode is Simple. In this method, only top-level keys are merged. For any top-level key you provide in the PATCH request, it will be added to the existing service properties if that key does not already exist, or it will replace that entire top-level key if it does exist.

Assuming an entity has the service properties shown at the top of this page, imagine sending a PATCH request with a mode=Simple query parameter (or no mode parameter at all) with this content:

{
	"alternateName": "Big Solar Farm",
	"sourceIdMap": {
		"/123789/inv/98766": "/INV/2"
	},
	"virtualSourceIds": [
		"/GEN/2"
	]
}

the resulting service properties would look like this:

{
	"alternateName": "Big Solar Farm",
	"apiKey": "{SSHA-256}aQrTEQH1rQoe...",
	"sourceIdMap": {
		"/123789/inv/98766": "/INV/2"
	},
	"virtualSourceIds": [
		"/GEN/2"
	]
}

☝️ Notice how the sourceIdMap object and virtualSourceIds array were completely replaced by the PATCH content. The alternateName property was added, and the apiKey property was preserved from the original service properties.

RecursiveObjects merge mode

The RecursiveObjects merge mode combines changes from arbitrarily nested objects within the service properties object. Following on from the example in the Simple section, if we sent the same PATCH request but with a mode=RecursiveObjects query parameter, the outcome would change to this:

{
	"alternateName": "Big Solar Farm",
	"apiKey": "{SSHA-256}aQrTEQH1rQoe...",
	"sourceIdMap": {
		"/123789/inv/98765": "/INV/1",
		"/123789/inv/98766": "/INV/2"
	},
	"virtualSourceIds": [
		"/GEN/2"
	]
}

☝️ Notice how the sourceIdMap object now contains entries from both the original service properties and the PATCH request. The virtualSourceIds array was still completely replaced by the PATCH content, however.

RecursiveObjectsAndArrays merge mode

The RecursiveObjectsAndArrays merge mode combines changes from arbitrarily nested objects and arrays within the service properties object. Following on from the example in the Simple section, if we sent the same PATCH request but with a mode=RecursiveObjectsAndArrays query parameter, the outcome would change to this:

{
	"alternateName": "Big Solar Farm",
	"apiKey": "{SSHA-256}aQrTEQH1rQoe...",
	"sourceIdMap": {
		"/123789/inv/98765": "/INV/1",
		"/123789/inv/98766": "/INV/2"
	},
	"virtualSourceIds": [
		"/GEN/1",
		"/GEN/2"
	]
}

☝️ Notice how the sourceIdMap object and virtualSourceIds array contain entries from both the original service properties and the PATCH request.