List products

GET

/api/v1/products

const url = 'https://example.com/api/v1/products';
const options = {
  method: 'GET',
  headers: {cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/products \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

What the participant offers, with how each product is delivered. Keys are masked.

Authorizations

session
viewer
dpop
viewer
bearer
viewer

Responses

200

OK.

application/json

A page of a list. next_cursor is null on the last page.

object

items

required

Array

A product as the management API shows it: key masked, plus how it is delivered.

object

required

string

title

required

string

description

string

keywords

Array<string>

content_type

string

profile

string

building_id

Building the dataset exposes (building_id in the wire protocol); published in the catalog so consumers can address it.

string | null

objects

Object ids of the product (decisions #67); building_id is the first.

Array<string>

sort

Readable kind of data, e.g. “Verlichting”, “Klimaat”, “Alle data”.

string | null

selection

One of:

All points of the objects.

object

kind

required

string

Allowed values: all

Chosen by hand: the product’s points.

object

label

string | null

kind

required

string

Allowed values: points

points

The resolved point list (a snapshot); None = all points of the objects.

Array<string> | null

points_resolved_at

string | null format: date-time

source_id

The own source that delivers this product.

string | null

backend

Own delivery: the internal API behind the dataset. Empty when a supplier delivers the dataset (delegation_id).

object

base_url

required

The address of the system, e.g. https://bms.example.nl/api.

string

auth_header_name

The header that carries the key, e.g. X-Api-Key.

string | null

auth_header_value

The key; shown as ••••••, and sent back as such it stays as it was.

string | null

allowed_methods

Methods the data plane lets through, e.g. ["GET"] for reading or ["GET", "POST", "PATCH"] for reading and steering. At least one: an empty list lets nothing through.

Array<string>

allowed_paths

Path patterns the data plane lets through (* one segment, ** the rest), e.g. api/sites/4711/**, or ["**"] for the whole API. At least one, except on a Buildinglinks system, whose koppelingen fill them (v1/buildings/{object}/**): an empty list lets nothing through.

Array<string>

links

Koppelingen that differ from the default, per object (decisions #72): the data plane routes the building to the system’s own id and key.

object

key

additional properties

How one object is reached in a system (decisions #72).

object

local_id

The system’s own id of the building; the default is the object id.

string | null

auth_header_value

A key for this building only; the default is the system’s.

string | null

provides

What the system provides for this building: data (the default), topology (the indeling, decisions #71) or both.

string | null

delegation_id

Delivery delegated to a supplier’s data plane (docs/decisions.md #32).

string | null

created_at

string format: date-time

delivery

required

How a product is delivered: from an own source, or by a supplier’s data plane under an erkenning en aanwijzing.

object

mode

required

own or delegated.

string

source_name

Own: the name of the source.

string | null

delegation_id

Delegated: the delegation.

string | null

supplier_did

string | null

supplier_name

string | null

state

Delegated: the state of the delegation, or unknown.

string | null

active

boolean | null

actions

Array<string> | null

valid_until

string | null format: date-time

role

One of:

null
string

null

initiated_by

One of:

null
string

null

awaits_us

Delegated: an open request or offer waits for our decision.

boolean | null

offers

Single product only: its offers.

Array<object> | null

An offer: a product with the policies under which it is in the catalog.

object

required

string

asset_id

required

The product.

string

access_policy_id

required

Who sees the offer in the catalog.

string

contract_policy_id

required

The conditions of the agreement.

string

approval

Whether a provider operator must approve each contract request.

string

Allowed values: automatic manual

created_at

string format: date-time

next_cursor

Pass as cursor for the next page.

string | null

Example

{
  "items": [
    {
      "selection": {
        "kind": "all"
      },
      "delivery": {
        "role": "delegator",
        "initiated_by": "delegator"
      },
      "offers": [
        {
          "approval": "automatic"
        }
      ]
    }
  ]
}

401

No valid session, DPoP-bound token or API key.

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

403

The caller lacks the role this operation needs; or a change with the session cookie came from a page of another site (cross_site_request, decisions #83).

application/json

The body of every failed call to a management API.

object

error

required

object

code

required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string

message

required

For people; may change between versions.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}