Ga naar inhoud
buildinglinksbuildinglinks

A provider's catalog

GET
/api/v1/dataspace/catalog
curl --request GET \
  --url 'https://example.com/api/v1/dataspace/catalog?participant=example' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

Asks the provider for its catalog over DSP, as this participant sees it, and returns it simplified: datasets with their objects and offers, each offer with its conditions.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
participant
required
string

The DID of the provider.

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

A provider’s catalog, simplified for the UI, with the DSP catalog as it came.

object
participant
required

A participant as the registry of the authority has it.

object
did
required
string
slug
required
string
name
required
string
legal_name
string
kvk_number
string | null
roles
Array<string>
dsp_endpoint
required
string
dataplane_url
string | null
color
string | null
status
required
string
health
string | null
datasets
required
Array<object>
object
id
required
string
title
required
string
description
required
string
keywords
required
Array<string>
building_id
string | null
objects
required
Array<string>
sort
string | null
delivered_by

The supplier that delivers on the provider’s behalf.

string | null
delivered_by_name
string | null
profile
required

https://w3id.org/buildinglinks/v1 or its topology profile.

string
offers
required
Array<object>
object
id
required

Pass as offer_id to start a negotiation or a connection.

string
policy_summary
required

The conditions in a sentence.

string
policy
required

The conditions in the terms of a policy here.

object
id
required
string
title
string
description
string | null
permissions
Array<object>

A permission, prohibition or obligation.

object
action
required

E.g. use, read, write.

string
constraints
Array<object>

A condition of a rule, e.g. bl:role isAnyOf [climate_optimizer].

object
left_operand
required

bl:membership, bl:role, bl:participant, odrl:dateTime, odrl:purpose or bl:signedRequests.

string
operator
required

eq, isAnyOf, isNoneOf, lt, lteq, gt or gteq.

string
right_operand
required

A string, a list of strings, a date-time or a boolean.

prohibitions
Array<object>

A permission, prohibition or obligation.

object
action
required

E.g. use, read, write.

string
constraints
Array<object>

A condition of a rule, e.g. bl:role isAnyOf [climate_optimizer].

object
left_operand
required

bl:membership, bl:role, bl:participant, odrl:dateTime, odrl:purpose or bl:signedRequests.

string
operator
required

eq, isAnyOf, isNoneOf, lt, lteq, gt or gteq.

string
right_operand
required

A string, a list of strings, a date-time or a boolean.

obligations
Array<object>

A permission, prohibition or obligation.

object
action
required

E.g. use, read, write.

string
constraints
Array<object>

A condition of a rule, e.g. bl:role isAnyOf [climate_optimizer].

object
left_operand
required

bl:membership, bl:role, bl:participant, odrl:dateTime, odrl:purpose or bl:signedRequests.

string
operator
required

eq, isAnyOf, isNoneOf, lt, lteq, gt or gteq.

string
right_operand
required

A string, a list of strings, a date-time or a boolean.

odrl
required

The offer as ODRL.

object
raw
required

The catalog as the provider sent it (DSP, JSON-LD).

object

Example generated

{
  "participant": {
    "did": "example",
    "slug": "example",
    "name": "example",
    "legal_name": "example",
    "kvk_number": "example",
    "roles": [
      "example"
    ],
    "dsp_endpoint": "example",
    "dataplane_url": "example",
    "color": "example",
    "status": "example",
    "health": "example"
  },
  "datasets": [
    {
      "id": "example",
      "title": "example",
      "description": "example",
      "keywords": [
        "example"
      ],
      "building_id": "example",
      "objects": [
        "example"
      ],
      "sort": "example",
      "delivered_by": "example",
      "delivered_by_name": "example",
      "profile": "example",
      "offers": [
        {
          "id": "example",
          "policy_summary": "example",
          "policy": {
            "id": "example",
            "title": "example",
            "description": "example",
            "permissions": [
              {
                "action": "example",
                "constraints": [
                  {
                    "left_operand": "example",
                    "operator": "example",
                    "right_operand": "example"
                  }
                ]
              }
            ],
            "prohibitions": [
              {
                "action": "example",
                "constraints": [
                  {
                    "left_operand": "example",
                    "operator": "example",
                    "right_operand": "example"
                  }
                ]
              }
            ],
            "obligations": [
              {
                "action": "example",
                "constraints": [
                  {
                    "left_operand": "example",
                    "operator": "example",
                    "right_operand": "example"
                  }
                ]
              }
            ]
          },
          "odrl": {}
        }
      ]
    }
  ],
  "raw": {}
}

401

Section titled “401”

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

Media typeapplication/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

Section titled “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).

Media typeapplication/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

Section titled “404”

Unknown participant.

Media typeapplication/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

Section titled “502”

The provider or the authority could not be reached.

Media typeapplication/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"
  }
}