Create a product

POST

/api/v1/products

const url = 'https://example.com/api/v1/products';
const options = {
  method: 'POST',
  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 POST \
  --url https://example.com/api/v1/products \
  --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" }'

A product names its objects, where the data comes from (an own source or a supplier’s delivery) and a selection of points. The selection is resolved into a point list now, from the source or the supplier.

Authorizations

session
operator
dpop
operator
bearer
operator

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

409

A product with this id exists, or the delivery cannot take products.

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

Create a product

Authorizations

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

409

Example

502

Example

Request Body^required