Test a source before saving it
const url = 'https://example.com/api/v1/sources/test';const options = { method: 'POST', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"object":"example","local_id":"example","auth_header_value":"example","provides":"example","source_id":"example","protocol":"example","health_path":"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"}}}}'};
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/sources/test \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "object": "example", "local_id": "example", "auth_header_value": "example", "provides": "example", "source_id": "example", "protocol": "example", "health_path": "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" } } } }'As testing a saved source, for an address, key and health path that are not saved yet. A masked key is the saved one of source_id.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”A system that is not saved yet (or saved with changes): its address,
key and health path. A masked key is the stored one of source_id.
object
The building to test; left out: test the system itself.
The system’s own id of the building.
A key for this building only; •••••• is the saved one.
data, topology or both.
The saved source this is a changed version of: its masked key and koppelingen count.
buildinglinks (default) or generic.
A path on the system that says whether it is up, e.g. health.
The binding of a dataset onto an internal API: where the data plane sends a request, with which key, and what it lets through.
object
The address of the system, e.g. https://bms.example.nl/api.
The header that carries the key, e.g. X-Api-Key.
The key; shown as ••••••, and sent back as such it stays as it was.
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.
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.
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
How one object is reached in a system (decisions #72).
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
Example generated
{ "object": "example", "local_id": "example", "auth_header_value": "example", "provides": "example", "source_id": "example", "protocol": "example", "health_path": "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" } } }}Responses
Section titled “Responses”The outcome, also when the test failed (ok: false).
The outcome of a test of a system or a koppeling, as the UI shows it.
object
system or koppeling.
Where it went wrong: unreachable, key, unknown, answer or invalid; null when ok.
The HTTP status of the system’s answer.
Milliseconds.
The request as sent, without the key: method, url, header (its name).
object
What came back: status, content_type, body (at most 64 KiB), bytes, truncated.
Koppeling: the building, and its id in the system.
Koppeling: how many points and locations the system listed.
Example generated
{ "kind": "example", "ok": true, "stage": "example", "status": 1, "ms": 1, "message": "example", "request": {}, "response": "example", "object": "example", "local_id": "example", "points": 1, "locations": 1}The request is not valid.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}No valid session, DPoP-bound token or API key.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}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).
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}