...

Authentication

OAuth

Client/Secret

UI URL: [CustomerName]-[Environment]-link.bizbrains.com/identity/clients

...

Use the above URL to request a new access token.

Resource Owner

A resource owner is another term for a standard Link user with the necessary role(s) for the given API.

Typically a “service user“ is created. This is a Link user created with the sole purpose of interacting with Link APIs.

Personal Access Token

Personal access tokens are created directly on a user’s details page in Link.

See the following article (Personal Access Token (PAT)) for a more detailed description of this authentication type.

Link APIs

See for the swagger for an overview of all available endpoints and a brief explanation of what each point does.

...

Navigating between Link API swagger documentations is done by change definition as shown below.

...

Link Inbox/Outbox

Inbox

Purpose: An endpoint to deliver a message to Link for processing. The request will contain the message itself and any relevant metadata.

...

Resource owner required role: API Transport

Outbox

Purpose: A series of endpoints used to create an outbound flow from Link to an end-system.

...

Resource owner required role: API Transport

Link REST

Configuration

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/configuration

...

Resource owner required role: API Configuration View

ConversionTable

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/conversions

...

Resource owner required role: API ConversionTable View

Document

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/entities/document

...

Resource owner required role: API Document View

Import

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/operation/import

Authentication type(s): OAuth, Resource Owner, Personal Access Token

Resource owner required role: API Import

Description:

This feature provides an alternative to using the UI to perform an import, but ultimately functions in the same way.

Just like the UI, the option to import data is separated into three areas: Partner, Distribution and Developer.

Importing data is a two step process and each area will have their own set of endpoints.

• The first step is sending an export file, generated through the UI, to the REST API for comparison. The file will be sent as a base64 encoded string as part of the request body. The response will contain a compare result, detailing how the exported data fits in compared to the existing data. It will also contain and overall status that will provide a quick way to determine if the file is valid to import.

• The second step is sending the compare result received as part of the previous step to the REST API. Given that the compare result is valid, then the data will be imported. If an invalid compare result is provided, the import will be aborted and no changes will have been saved.

See the swagger for examples of all requests and responses.

Roles and permissions

There is a permission specific to each of the previously mentioned data areas.

• “API Import Partner“ (API_Import_Partner)

• “API Import Distribution“ (API_Import_Distribution)

• “API Import Developer“ (API_Import_Developer)

These are all part of the “API Import“ role.

Tracking

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/operation/tracking

Authentication type(s): OAuth, Resource Owner, Personal Access Token

Resource owner required role: API Tracking

Async Tracking (for releases after 2024-01-25)

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/operation/async-tracking

Authentication type(s): OAuth, Resource Owner, Personal Access Token

Resource owner required role: API Tracking

The main purpose of the asynchronous tracking interface is to allow faster tracking than with the synchronous tracking by making each tracking independent of the others, so that the tracking party can continue its work without waiting for trackings to complete. Because each tracking request needs to be independent of any others, the async tracking interface changes the way that interchanges and documents are identified. In the synchronous tracking scenario the server generates identifiers and the tracking party has to wait for the identifier before it can generate the next tracking. With asynchronous tracking, the tracking partner assigns a guid to each interchange and document and use these to continue tracking without waiting. When trackings are persisted to the Link database identifiers are still generated as usual, but the individual tracking calls are resolved using the guids.

In order to facilitate the needed processing speed, async tracking calls do not update Link in real time. Instead, the calls are simply persisted to a staging database, from which they can be synchronized to Link via a scheduler task using the “Async tracking synchronization” scheduler task handler. This means that tracking data sent to Link using the async tracking interface will not be immediately available in Link, only after the next time the synchronization scheduler task runs. This is a necessary tradeoff in order to achieve the near-instantaneous processing of the tracking requests.

Developing with Bizbrains.Link.Api.Proxy

Link3Public Nuget URL: https://bizbrains-productteam.visualstudio.com/Link3Public/_artifacts/feed/Link3Public

In the Link3Public feed there is a package called Bizbrains.Link.Api.Proxy which helps facilitate communication with the Link REST API.

Link AS2

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/transport/as2

Authentication type(s): None

Link AS4

Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/transport/as4

Authentication type(s): None

Generic Http Handler

If there is a more specific action that is not supposed by any of the above APIs out of the box, then there is the option of creating a plugin for the generic http handler.

...