What is generated automatically
UBC Data Bridge generates an HTML technical reference for an API endpoint from its saved settings. It describes the actual address, data format, fields, validation rules, parameters, responses and effective limits. The flow author and integrator can work from one contract as the schema or execution method changes.
For intake, examples reflect the body or file format, mock data, required fields and unique keys. For publication, they reflect stored results or execution on demand, response format, filters and pagination. The reference shows the endpoint's state: saving a draft does not mean its changes are already active in Production.
1. Prepare the endpoint contract
- Name the connection and flow so the partner understands the dataset, for example “Store inventory — test”.
- Complete address and format settings. For intake, enter a small valid example, refresh fields and check types, required flags and keys.
- For publication, connect the intended result, choose the execution mode and describe parameters in plain language. Confirm which are required.
- Save connection and block settings. Preview and simulate, resolve errors, then publish the agreed flow version.
- Reopen the reference after changes. Match the address, Production state and response example to what the client should use.
2. Open the reference and grant access
Use “Technical documentation” in API block properties or the saved publication connection. “API → Documentation” lists accessible endpoints. The block reference route is /api/flows/{flow}/blocks/{node}/api-docs; publication connection, /api/connections/{connection}/api-docs; catalog, /api/api-docs. Add the installation prefix.
Opening the reference requires a signed-in Data Bridge user. Access belongs to a flow editor or a user with the “API documentation” role permission who can view the flow. An API key alone does not open the HTML reference. Making data publication public does not make the reference public. Give the integrator appropriate account access and transfer the request key separately.
3. Configure a client from the examples
Begin with “Quick start”: copy the address and configure Postman or curl. The reference includes Python examples and authentication guidance. If relevant API clients require HMAC, signing instructions appear; follow your own key's settings. “Copy” controls next to addresses and code transfer examples without manual retyping.
Insert test values and your own key in a secure local environment. The reference contains no client secrets. For JSON, preserve structure and the array path; for CSV, delimiter and headers; for files, transmission method and filename. Do not substitute the mock's input format for the request format: these are independent settings.
4. Verify success and expected rejection
For intake, send a small valid request, wait for delivery completion and reconcile the destination result. Then test a missing required field, invalid type, duplicate unique key and repeated delivery using the same Idempotency-Key. Rejection should be understandable to the client, and replay should not create an additional run.
For publication, test the first and next page, a required filter, an empty selection and stale data. In execution mode, follow next with the fixed run.id until completion. Separately test an invalid key, forbidden flow and rate limit. Record HTTP status, error code, delivery/run and expected row count.
5. Maintain the operational contract
Match a failed request to “Settings → API → Request audit” or “API requests” in the block menu. Check method, direction, status, duration and response. Body recording depends on audit settings: bodies can contain business data, so select the necessary recording scope and retention.
The reference's limits table shows effective values: request size, queue, waiting time, page size and other settings relevant to that endpoint. Reopen it after limit changes. Delivery input data is cleaned up after completion; run history and audit have their own retention rules. When changing a partner contract, use a new address version and agree on migration while retaining the old version during transition.