Basic concepts

Navarik Bridge API is an integration platform providing a way for cargo shippers and inspection companies to securely and transparently share inspection-related data. Navarik Bridge APIs can be used directly (e.g. through command-line tools) or integrated with other software systems. Bridge APIs are being developed primarily to support integration with Navarik Inspection and Navarik Inspection Manager, however, the base concepts are generic enough to support other potential use-cases.

Organization registry

One of the key concepts of Bridge API is "Organization". An organization represents one of the integrating parties and organization IDs play a key role in setting up integration workspaces. Organization names and IDs are visible to all Bridge users, but any details about your organization are only visible to you. In this Bridge Organizations differ from Navarik ID organizations (also known as Navarik Platform tenants or clients). The public ID of your organization in the Bridge cannot be used to access your Navarik platform tenant information.

Workspaces

An "integration workspace" (a "Bridge workspace", or simply "Workspace") is the main part of Navarik Bridge. It is a virtual space created to between integrating parties to securely share structured and binary documents. Workspaces come with built-in security controls preventing unauthorized parties from accessing the shared data. Each document in the workspace has its own unique URL that is accessible by any authorized user. For more information, see Workspaces (opens new window).

Navarik Bridge currently supports only one type of workspaces designed for integrating cargo shippers and inspection companies, however we plan to have more options in the future. Also, it's important to note that Bridge API functionality is not limited to Navarik Inspection clients and can be used for integrating with any cargo shipper.

Documents and Attachments

In Bridge, information is exchanged between the integrating parties using objects documents and file attachments.

Workspace Documents are machine-readable JSON objects, sometimes referred to also as "entities" or "business objects". Each document belongs to a particular type and its body must be formatted according to that type's schema, for example: Inspection Worksheet (opens new window). Bridge APIs use generic Entity Envelope format when working with Documents.

Attachments are binary data associated with a workspace document, e.g. PDFs, Excel spreadsheets, etc. These data are not machine-readable and are meant to be used by the end user, for example the Inspection Company might submit an official certificate of analysis as a PRF attachment to their worksheet document.

All workspace content belongs to a particular workspace and cannot be shared with other workspaces using Bridge APIs. Workspace documents can not reference entities outside their workspace. Only users from the integration parties have access to the content of their workspace. In order to make this requirement easier to follow, most of RESTful Bridge APIs have workspace ID in their resource URL.

Catalogs and catalog mappings

Probably the most complicated part of the Bridge APIs is the catalog mapping subsystem. Bridge accepts external IDs (xref) and names for data fields that should be represented as catalog references in one or both integrating systems. For example, transports, products, uom (units of measure), etc. The system automatically keeps track of the records provided along with the documents as they come through the APIs for both integrating parties. For example, if you create a job and specify "Tanker 1234" with an xref = 1234 as a transport, a record will be added for it in the transport catalog in your workspace. The system then will try to reuse existing catalog records when the user uses the same xref in their new documents. See more details in External References (opens new window).

In addition to managing catalog records, Bridge API provides a way to link different catalog records together as synonyms. The idea is to provide integrators with an API allowing them to match IDs from their catalogs to IDs from their counterparty's catalogs without the need to maintain a central master record system. For more details, see Synonyms (opens new window).