Change a product

PUT

/api/v1/products/{id}

const url = 'https://example.com/api/v1/products/example';
const options = {
  method: 'PUT',
  headers: {
    cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E',
    'Content-Type': 'application/json'
  },
  body: '{"id":"example","title":"example","description":"example","keywords":["example"],"objects":["example"],"building_id":"example","sort":"example","selection":{"kind":"all"},"points":["example"],"source_id":"example","delegation_id":"example","backend":{"base_url":"example","auth_header_name":"example","auth_header_value":"example","allowed_methods":["example"],"allowed_paths":["example"],"links":{"additionalProperty":{"local_id":"example","auth_header_value":"example","provides":"example"}}},"content_type":"example","profile":"example"}'
};

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

curl --request PUT \
  --url https://example.com/api/v1/products/example \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "id": "example", "title": "example", "description": "example", "keywords": [ "example" ], "objects": [ "example" ], "building_id": "example", "sort": "example", "selection": { "kind": "all" }, "points": [ "example" ], "source_id": "example", "delegation_id": "example", "backend": { "base_url": "example", "auth_header_name": "example", "auth_header_value": "example", "allowed_methods": [ "example" ], "allowed_paths": [ "example" ], "links": { "additionalProperty": { "local_id": "example", "auth_header_value": "example", "provides": "example" } } }, "content_type": "example", "profile": "example" }'

Replaces the product. How it is delivered stays as it is. An unchanged selection keeps its point list.

Authorizations

session
operator
dpop
operator
bearer
operator

Parameters

Path Parameters

required

string

The id of the product.

Request Body^required

application/json

A product as the API accepts it. building_id and backend are the fields from before sources (an own binding per product).

object

Left out on create: made from the title.

string | null

title

string

description

string

keywords

Array<string>

objects

The object ids, e.g. nl.bag.pand.0014100040022681.

Array<string>

building_id

Older single object; objects wins.

string | null

sort

A readable kind of data, e.g. “Klimaat”; derived when left out.

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

With selection points: the points chosen by hand.

Array<string> | null

source_id

The own source that delivers the product.

string | null

delegation_id

Create only: the delivery by a supplier this product belongs to.

string | null

backend

One of:

null
object

null

A binding of its own, from before sources; not with source_id or 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

content_type

Default application/json.

string | null

profile

https://w3id.org/buildinglinks/v1 or its topology profile; settled by where the data comes from.

string | null

Responses

200

OK.

application/json

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

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

Example

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

400

The request is not valid.

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"
  }
}

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"
  }
}

404

Not found.

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"
  }
}

502

The points could not be read from the source.

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"
  }
}

Change a product

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

502

Example

Request Body^required