Subscriptions

search subscriptions

get

List all subscriptions. May filter results by programID and clientName as query params. May filter results by targetType and targetValues as query params. May filter results by objects as query param. See objectTypes schema. Use skip and pagination query params to limit response size.

Authorizations

Query parameters

programIDstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

clientNamestringOptional

filter results to subscriptions with clientName.

targetTypestringOptional

Indicates targeting type, e.g. GROUP

targetValuesstring[]Optional

List of target values, e.g. group names

skipinteger · int32Optional

number of records to skip for pagination.

limitinteger · int32 · max: 50Optional

maximum number of records to return.

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

get

HTTPcURLJavaScriptPython

GET /api/openadr/v1/subscriptions HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

[
  {
    "id": "object-999",
    "createdDateTime": "2023-06-15T09:30:00Z",
    "modificationDateTime": "2023-06-15T09:30:00Z",
    "objectType": "SUBSCRIPTION",
    "clientName": "VEN-999",
    "programID": "object-999",
    "objectOperations": [
      {
        "objects": [
          "EVENT"
        ],
        "operations": [
          "POST"
        ],
        "callbackUrl": "https://myserver.com/send/callback/here",
        "bearerToken": "NCEJGI9E8ER9802UT9HUG"
      }
    ],
    "targets": [
      {
        "type": "PRICE",
        "values": [
          0.17
        ]
      }
    ]
  }
]

create subscription

post

Create a new subscription.

Authorizations

Body

An object created by a client to receive notification of operations on objects. Clients may subscribe to be notified when a type of object is created, updated, or deleted.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator.

Possible values:

clientNamestring · min: 1 · max: 128Required

User generated identifier, may be VEN identifier provisioned out-of-band.

Example: VEN-999

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

201

Created.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

409

Conflict. Implementation dependent response if identical object already exists.

application/json

500

Internal Server Error.

application/json

post

HTTPcURLJavaScriptPython

POST /api/openadr/v1/subscriptions HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

search subscriptions by ID

get

Return the subscription specified by subscriptionID specified in path.

Authorizations

Path parameters

subscriptionIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

get

HTTPcURLJavaScriptPython

GET /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

update subscription

put

Update the subscription specified by subscriptionID specified in path.

Authorizations

Path parameters

subscriptionIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Body

An object created by a client to receive notification of operations on objects. Clients may subscribe to be notified when a type of object is created, updated, or deleted.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator.

Possible values:

clientNamestring · min: 1 · max: 128Required

User generated identifier, may be VEN identifier provisioned out-of-band.

Example: VEN-999

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

409

Conflict. Implementation dependent response if program with the same programName exists.

application/json

500

Internal Server Error.

application/json

put

HTTPcURLJavaScriptPython

PUT /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

delete subscription

delete

Delete the subscription specified by subscriptionID specified in path.

Authorizations

Path parameters

subscriptionIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

delete

HTTPcURLJavaScriptPython

DELETE /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer JWT
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}