Communication Protocol

Updated 1 hour ago by John Heggelund

The EPCIS 2.0 standard defines how traceability data is queried and captured, within a company and between companies. Organizations following the GDST (Global Dialogue on Seafood Traceability) standard implement the EPCIS Query Interface as a REST interface, as defined by EPCIS 2.0 and described concretely by OpenAPI definition file.

The full EPCIS Query Interface is extensive. To keep implementation manageable, the GDST standard requires only a defined subset, described below, together with a GS1 Digital Link resolver for discovery, an authentication mechanism, and the business-to-business exchange workflow.

This article covers four parts:

1. The EPCIS Query Interface (how data is requested)
2. The GS1 Digital Resolver (how a repository is discovered)
3. Authentication (how requests are secured)
4. The business-to-business data exchange workflow (how it all fits together)

EPCIS Query Interface

The Query Interface follows REST principles. The following method must be implemented.

GET /events

Requests all the events in the repository, or the subset of events matching the criteria supplied as query parameters in the URL.

Responses must be returned in the EPCIS 2.0 JSON-LD format.

Query Parameters

The interface must support the following query parameters, whether used in a named query or directly in the request URL.

GS1 Digital Link Resolver

A GS1 Digital Link resolver acts as a lookup service, a kind of "pseudo-DNS", that turns an identifier into links to the information about it. Organizations following the GDST standard must implement a resolver as defined by GS1 Digital Link standard.

Required Link Types

Required Application Identifiers

URL paths use numeric GS1 application identifiers. as of Digital Link 1.1.3, the numeric identifier must be used, the alphabetic from (e.g. gtin) is no longer allowed, so a URL uses 01 before a GTIN, not gtin.

URL Structure

A Digital Link URL is built as {Base URL}/{Application Identifier}/{Value}/{Application Identifier 2}/{Value 2} , with the application identifiers in a specific order. For example:

https://resolver.example.org/01/00860003130308/10/LOT07082021

The supported application-identifier pairs are:

Resolving a Digital Link URI

To resolve a Digital Link URI, replace the canonical base URL, with the base URL of the sender´s resolver. For example, a PGLN identifier https://id.gs1.org/417/0860003130308 resolved against a sender´s resolver https://resolver.example.org/ becomes:

Example Request

GET /417/0860003130308?linkType=linkset HTTP/1.1
          Host: https://resolver.example.org
          X-API-KEY: <api-key>
          https://resolver.example.org/417/0860003130308

Example Response

{
              "linkset": [
                  {
                      "anchor": "https://resolver.example.org/digitallink/01/urn:gdst:example.org:product:class:system.processedfish",
                      "itemDescription": null,
                      "https://ref.gs1.org/voc/defaultLink": [
                          {
                              "href": "https://resolver.example.org/masterdata/product/urn:gdst:example.org:product:class:system.processedfish",
                              "title": "Default Master Data"
                          }
                      ],
                      "https://ref.gs1.org/voc/masterData": [
                          {
                              "href": "https://resolver.example.org/masterdata/product/urn:gdst:example.org:product:class:system.processedfish",
                              "title": "Master Data"
                          }
                      ],
                      "https://ref.gs1.org/voc/epcis": [
                          {
                              "href": "https://resolver.example.org/epcis",
                              "title": "EPCIS Repository"
                          }
                      ]
                  }
              ]
          }

Resolver Responses

The digital link resolver is

Authentication

The two parties exchanging data exchange API keys to access each other´s EPCIS Query Interface. Each request from the receiver to the sender carries the key in an HTTP header:

X-API-Key: 81C6C194-B445-4FFB-907E-CDBC7FF7F36F

Authentication is not required by EPCIS 2.0 standard, but it expected to occur. At a minimum, implementations following the GDST standard must support the X-API-Key header. If both providers support another security protocol and prefer it, they use it instead, the standard only mandates that X-API-Key is supported.

It is entirely up to sender to manage, generate, and authenticate API keys, the standard only specifies where to place and look for the key. Some cases may not require authentication at all, for example, a brand owner exposing public (or redacted) traceability data to consumers, or sharing trade-item information such as coupons or recipes through their resolver.

Business-to-Business Data Exchange

In a B2B exchange, the Receiver is the party requesting traceability data and the Sender is the party providing it (typically the Receiver is receiving goods, and the Sender is transferring them).

Before exchanging traceability data, the two parties first exchange company information to establish each other in their systems. The GDST proposes sharing at minimum:

• A GS1 Digital Link URI plus the party´s GLN, and
• an API key

This lets each party request the master data describing a party or location (not just an object).

Once established, typical exchange runs as follows: The Receiver takes a product identifier (often obtained from an earlier step, such as an Advanced Shipment Notification through an ERP system), formats it as a GS1 Digital Link URI, and queries the Sender´s Digital Link resolver to discover the location of Sender´s EPCIS repository. The Receiver then queries that EPCIS Query Interface to obtain the events and master data for the products. All requests use HTTP following REST, and responses are returned in EPCIS 2.0 JSON-LD format.

How did we do?