Link API
This article gives an overview of the different APIs available in Link and the prerequisites on how to use them.
Authentication
OAuth
Client/Secret
UI URL: [CustomerName]-[Environment]-link.bizbrains.com/identity/clients
In order to use OAuth, the necessary client(s) must be created in Link. When selecting scopes it is required that API is selected.
Token URL: [CustomerName]-[Environment]-api-link.bizbrains.com/connect/token
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.
Swagger URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/swagger/index.html
Navigating between Link API swagger documentations is done by change definition as shown below.
Selecting a definition
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.
Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/transport/inbox
Authentication type(s): OAuth, Resource Owner, Personal Access Token
Resource owner required role: API Transport
Outbox
Purpose: A series of endpoints used to create an outbound flow from Link to an end-system.
Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/transport/outbox
Authentication type(s): OAuth, Resource Owner, Personal Access Token
Resource owner required role: API Transport
Link REST
Configuration
Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/configuration
Authentication type(s): OAuth, Resource Owner, Personal Access Token
Resource owner required role: API Configuration View
ConversionTable
Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/conversions
Authentication type(s): OAuth, Resource Owner, Personal Access Token
Resource owner required role: API ConversionTable View
Document
Base URL: [CustomerName]-[Environment]-api-link.bizbrains.com/api/rest/entities/document
Authentication type(s): OAuth, Resource Owner, Personal Access Token
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.
See the following article (Generic Http Handler ) for more details.