This page contains the shared conventions used by the built-in API guides. Each area guide describes its own operations, permissions, and data effects.
Environment and API definitions
Obtain your environment's API address from its administrator. Examples use https://<yourcompany>-link-api.bizbrains.com; replace this with your address, including any externally configured gateway mapping.
Open /api/swagger/index.html and select a definition. Link REST contains Artifact, Tracking, Async Tracking, Document, Configuration, ConversionTable, Import, and AsyncFlow operations. Inbox/Outbox and AS2/AS4 have separate definitions. A definition describes the installed version; its presence in another environment does not establish availability in yours.
The REST guides use /api/rest. A Swagger definition labelled v1 does not imply an extra /v1 in every URL. Inbox/Outbox version routes are explained in [Inbox/Outbox versions](inbox-outbox-versions.md).
Authentication and permissions
Use the existing API Authentication guide to set up OAuth or a PAT. OAuth integrations use the supported user-based flow described there; a client ID and secret do not imply support for the Client Credentials grant.
A role groups permissions. Each API operation checks a permission, even when the administration UI presents it through a predefined role. REST actions using the shared permission filter also require the api scope. Grant the service user the permissions listed in the relevant area guide.
Examples use Bash, curl with --fail-with-body support, and these placeholders:
LINK_API_BASE='https://<yourcompany>-link-api.bizbrains.com'
LINK_PAT='<your-personal-access-token>'
--user ":${LINK_PAT}" sends the PAT as the Basic password with an empty username. For OAuth, replace that option with --header "Authorization: Bearer ${LINK_ACCESS_TOKEN}". Examples using jq require that command-line JSON tool. In scripts that perform dependent calls, stop on a failed request before continuing.
Shared terms
|
Term |
Meaning |
|---|---|
|
Document |
A business document represented by a Link tracking record |
|
Incoming interchange |
The incoming transmission, which can contain several documents |
|
Outgoing interchange |
The outgoing transmission, which can batch several documents |
|
Entity ID |
A numeric Link database identifier; use the identifier for the entity type required by the operation |
|
GUID |
A separate globally unique reference; a document GUID and interchange GUID identify different entities |
|
Partner identification |
A qualifier/value pair used to resolve a partner, such as a configured GLN identification |
|
Partner key |
The partner's Link key, also called EdiPortalId in some contracts; it is not an arbitrary identification value |
|
Document status |
A configured lifecycle status, such as Completed or Failed |
|
Technical status |
A log entry describing an event without necessarily changing the document's lifecycle status |
An API permission and a partner filter serve different purposes. Do not assume an API automatically applies the same partner restrictions as another API or the UI; each guide states the relevant access rules.
Requests and responses
Use application/json for JSON request bodies. Raw file operations specify their own body format. Percent-encode individual URL path and query values; base64 content inside JSON and URL encoding are different encodings.
REST JSON request and response properties normally use camelCase. An empty 200 or 204 response must not be parsed as a JSON object. A 202 response means the request was accepted for deferred processing; the area guide explains when its effects become visible.
Errors and retries
Unhandled exceptions passing through the REST error middleware return JSON with ErrorMessage, ErrorTimeUtc, and ReferenceId. Keep those values for support. This middleware defaults to HTTP 500 unless the exception explicitly supplies another status. Do not infer 400 from an exception's .NET type or from its message.
Error formats vary: permission-filter denials can be plain text, model validation can return a different JSON structure, callbacks have their own response, and gateways can return HTML or no body. Check the HTTP status and content type before parsing.
Authentication failures commonly return 401. The shared REST permission filter returns 403 for a missing permission or required scope; some older authorization policies and domain-specific access checks have different responses. Each area guide documents important exceptions.
A timeout or connection loss does not prove that a write was rolled back. Check its result before retrying. A repeated write can create duplicates or repeat side effects; use the area's reconciliation rules rather than enabling automatic retries for every POST.
Request sizes and timeouts depend on the host and gateway. REST hosts can use Link:Http:MaxRequestBodySize; proxy limits may be lower. Large base64 JSON values also have serialization limits, and base64 increases transfer size. The Inbox/Outbox version guide explains the relevant payload-format differences.