### Run Kafka Topic Setup with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Executes a one-time Kafka topic setup using Podman Compose. This is a required step before starting the REST API.

```shell
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
```

--------------------------------

### Start OpenEPCIS Community Edition with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/examples/getting-started/CAPTURE.md

Launches the Community Edition of OpenEPCIS using Podman Compose. Includes Kafka topic setup and restarting the REST API. Check logs for status.

```shell
# OR: Start Community Edition (XSLT-based)
podman-compose -f docker-compose.yml -f docker-compose.rest-api-ce.yml up -d

# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-ce

# check logs
podman logs --tail 250 -f quarkus-rest-api-ce
```

--------------------------------

### Run Kafka Topic Setup with Docker

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Executes a one-time Kafka topic setup using Docker Compose. This is a required step before starting the REST API.

```shell
docker compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
```

--------------------------------

### Start OpenEPCIS Research Edition with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/examples/getting-started/CAPTURE.md

Launches the Research Edition of OpenEPCIS using Podman Compose. Includes Kafka topic setup and restarting the REST API. Check logs for status.

```shell
# Start Research Edition (SAX-based)
podman-compose -f docker-compose.yml -f docker-compose.rest-api-re.yml up -d

# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-re

# check logs
podman logs --tail 250 -f quarkus-rest-api-re
```

--------------------------------

### Business Step Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Example JSON response body for the business steps endpoint, listing various business step names.

```json
{
  "bizSteps": [
    "shipping",
    "receiving",
    "packing",
    "unpacking",
    "manufacturing",
    "storing"
  ]
}
```

--------------------------------

### Clone Repository and Navigate to Docker Directory

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Clone the OpenEPCIS repository and navigate to the docker directory to begin the setup process.

```shell
git clone https://github.com/openepcis/epcis-repository-ce.git
cd epcis-repository-ce/docker
```

--------------------------------

### Generate and Capture Example Events

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/examples/getting-started/CAPTURE.md

Generate test EPCIS events using the OpenEPCIS test data generator and send them directly to the repository for capture. This example assumes custom extensions are not used.

```shell
curl --header "Content-Type: application/json" "https://tools.openepcis.io/api/generateTestData?pretty=true" -d \
'{
    "events": [
        {
            "nodeId": 1,
            "eventType": "ObjectEvent",
            "eventCount": 25,
            "locationPartyIdentifierSyntax": "WebURI",
            "dlURL": "https://id.gs1.org",
            "seed": 1748412892328,
            "ordinaryEvent": true,
            "action": "ADD",
            "eventID": false,
            "eventTime": {
                "timeZoneOffset": "+02:00",
                "fromTime": "2025-01-01T08:14:52+02:00",
                "toTime": "2025-05-28T08:14:52.000+02:00"
            },
            "businessStep": "COMMISSIONING",
            "disposition": "ACTIVE",
            "certificationInfo": [
                {
                    "extensionID": 0,
                    "prefix": "",
                    "contextURL": "",
                    "children": []
                }
            ],
            "userExtensions": [
                {
                    "extensionID": 8059,
                    "prefix": "",
                    "contextURL": "",
                    "children": []
                }
            ],
            "ilmd": [
                {
                    "extensionID": 7040,
                    "prefix": "",
                    "contextURL": "",
                    "children": []
                }
            ],
            "referencedIdentifier": [
                {
                    "identifierId": 1,
                    "epcCount": 1,
                    "classCount": 0
                }
            ],
            "parentReferencedIdentifier": {},
            "outputReferencedIdentifier": []
        }
    ],
    "identifiers": [
        {
            "identifierId": 1,
            "objectIdentifierSyntax": "WebURI",
            "dlURL": "https://id.gs1.org",
            "instanceData": {
                "sgtin": {
                    "identifierType": "sgtin",
                    "gcpLength": "",
                    "serialType": "range",
                    "sgtin": "09526545673796",
                    "rangeFrom": 1000000,
                    "count": 1,
                    "ID": 1
                }
            },
            "classData": null,
            "parentData": null
        }
    ],
    "randomGenerators": [
        {
            "name": "RND_0-1",
            "minValue": 0,
            "maxValue": 1,
            "meanValue": 0.5,
            "seedValue": 1747115247162,
            "distributionType": "TriangularDistribution",
            "randomID": 1
        }
    ],
    "contextUrls": []
}' -o - | curl --header "Content-Type: application/ld+json" "http://localhost:8080/capture" -d @-
```

--------------------------------

### Start OpenEPCIS CE with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Launches the Community Edition REST API using Podman Compose. Ensure the necessary Compose files are present.

```shell
podman-compose -f docker-compose.yml -f docker-compose.rest-api-ce.yml up -d
```

--------------------------------

### Query Language Examples

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-events.md

Provides examples of how to query EPCIS events using various parameters, including filtering by event type, time window, business step, disposition, and using pagination tokens.

```APIDOC
## Query Language Examples

### Find all ObjectEvents in a time window
```
GET /events?eventType=ObjectEvent&GE_eventTime=2022-06-30T00:00:00Z&LT_eventTime=2022-07-01T00:00:00Z
```

### Find events by business step and disposition
```
GET /events?EQ_bizStep=shipping&EQ_disposition=in_transit
```

### Find events with pagination
```
GET /events?eventType=AggregationEvent&perPage=50&nextPageToken=3A15506738...
```

### Find events by read point (wildcard)
```
GET /events?WD_readPoint=urn:epc:id:sgln:0012345.11111.*
```
```

--------------------------------

### Disposition Examples

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Example JSON response body for the /dispositions endpoint, showing a list of disposition names used in captured events.

```json
{
  "dispositions": [
    "in_transit",
    "no_pedigree_flag",
    "completeness_verified",
    "completeness_suspicious",
    "all_data_present"
  ]
}
```

--------------------------------

### Example EPCIS Query for Action

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/types.md

Demonstrates how to query EPCIS events filtering by a specific action, such as 'ADD'.

```http
GET /events?EQ_action=ADD
```

--------------------------------

### 404 Not Found Error Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of a not found error response when a requested resource does not exist or an ID is invalid.

```json
{
  "type": "urn:epcis:error:notfound",
  "title": "Not Found",
  "detail": "Event with ID 'urn:epc:event:unknown' does not exist",
  "instance": "/events/urn:epc:event:unknown",
  "status": 404
}
```

--------------------------------

### Basic Authentication Header

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Example of how to format the Authorization header for Basic Authentication.

```http
Authorization: Basic base64(user:pass)
```

--------------------------------

### Run OpenEPCIS Community Edition with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Start the Community Edition REST API using Podman Compose. This includes setting up Kafka topics and checking logs.

```shell
# Create VM for 8GB of memory and 8 CPUs
podman machine init --memory=8192 --cpus=8

# and start it
podman machine start
```

```shell
podman-compose -f docker-compose.yml -f docker-compose.rest-api-ce.yml up -d

# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-ce

# check logs
podman logs --tail 250 -f quarkus-rest-api-ce
```

--------------------------------

### Start OpenEPCIS RE with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Launches the Research Edition REST API using Podman Compose. Ensure the necessary Compose files are present.

```shell
podman-compose -f docker-compose.yml -f docker-compose.rest-api-re.yml up -d
```

--------------------------------

### Start OpenEPCIS CE with Docker

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Launches the Community Edition REST API using Docker Compose. Ensure the necessary Compose files are present.

```shell
docker compose -f docker-compose.rest-api-ce.yml up -d
```

--------------------------------

### Start OpenEPCIS RE with Docker

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Launches the Research Edition REST API using Docker Compose. Ensure the necessary Compose files are present.

```shell
docker compose -f docker-compose.rest-api-re.yml up -d
```

--------------------------------

### Run OpenEPCIS Community Edition with Docker

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Start the Community Edition REST API using Docker Compose. This includes setting up Kafka topics and checking logs.

```shell
docker compose -f docker-compose.rest-api-ce.yml up -d

# Run one-time Kafka topic setup
docker compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-ce

# check logs
docker logs --tail 250 -f quarkus-rest-api-ce
```

--------------------------------

### OPTIONS /capture Request Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Use the OPTIONS method on the /capture endpoint to discover capabilities and limits of the capture endpoint, such as supported versions and size limits.

```http
OPTIONS /capture HTTP/1.1
Host: localhost:8080
```

--------------------------------

### Subscribe to Multiple Queries

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-websocket.md

This example shows how to establish simultaneous subscriptions to multiple EPCIS queries using the WebSocket client. Each subscription is handled independently.

```java
@Inject
WebSocketClient wsClient;

public void subscribeToMultiple() {
    // Query 1
    wsClient.querySubscription("query1", event1 -> {
        System.out.println("Query1: " + event1.getEventId());
    }).subscribe().with(s1 -> {
        System.out.println("Connected to query1");
    });
    
    // Query 2
    wsClient.querySubscription("query2", event2 -> {
        System.out.println("Query2: " + event2.getEventId());
    }).subscribe().with(s2 -> {
        System.out.println("Connected to query2");
    });
}
```

--------------------------------

### Run OpenEPCIS Research Edition with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Start the Research Edition REST API using Podman Compose. This includes setting up Kafka topics and checking logs.

```shell
podman-compose -f docker-compose.yml -f docker-compose.rest-api-re.yml up -d

# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-re

# check logs
podman logs --tail 250 -f quarkus-rest-api-re
```

--------------------------------

### Capture GS1 Example Events

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/examples/getting-started/CAPTURE.md

Use curl to download and post GS1 reference event files directly to the OpenEPCIS capture endpoint.

```shell
curl -o - "https://ref.gs1.org/docs/epcis/examples/example_9.6.1-object_event.jsonld" | \
curl --header "Content-Type: application/ld+json" "http://localhost:8080/capture" -d @-
```

```shell
curl -o - "https://ref.gs1.org/docs/epcis/examples/sensor_data_example1.jsonld" | \
curl --header "Content-Type: application/ld+json" "http://localhost:8080/capture" -d @-
```

--------------------------------

### Submit and Query EPCIS Events with Java Client

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-low-level.md

This example demonstrates how to submit events using `epcisClient.capture().capturePost()` and query them using `epcisClient.events().eventsGet()`. It shows basic error handling for submission and event processing for query results. Ensure the `LowLevelEPCISClient` is properly injected.

```java
import io.smallrye.mutiny.Uni;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.core.MultivaluedHashMap;
import jakarta.ws.rs.core.MultivaluedMap;
import jakarta.ws.rs.core.Response;
import java.io.InputStream;

// Assuming EPCISQueryDocument and related classes are defined elsewhere
// import com.example.epcis.EPCISQueryDocument;

@ApplicationScoped
public class EpcisEventProcessor {
    
    @Inject
    LowLevelEPCISClient epcisClient;
    
    public void processWorkflow() {
        // Step 1: Submit events
        submitEvents();
        
        // Step 2: Query submitted events
        queryEvents();
    }
    
    private void submitEvents() {
        InputStream eventData = /* read from file */ null;
        
        Uni<Response> capture = epcisClient.capture()
            .capturePost(eventData);
        
        capture.subscribe().with(resp -> {
            if (resp.getStatus() == 202) {
                String captureId = extractCaptureIdFromLocation(
                    resp.getHeaderString("Location")
                );
                System.out.println("Submitted with ID: " + captureId);
            }
        });
    }
    
    private void queryEvents() {
        MultivaluedMap<String, String> params = new MultivaluedHashMap<>();
        params.add("eventType", "ObjectEvent");
        params.add("GE_eventTime", "2024-01-01T00:00:00Z");
        params.add("perPage", "100");
        
        Uni<Response> query = epcisClient.events()
            .eventsGet(params, new MultivaluedHashMap<>());
        
        query.subscribe().with(resp -> {
            // Assuming EPCISQueryDocument is the correct entity type
            // EPCISQueryDocument doc = resp.readEntity(EPCISQueryDocument.class);
            // doc.getEvents().forEach(event -> {
            //     System.out.println("Found event: " + event.getEventId());
            // });
            System.out.println("Query response status: " + resp.getStatus());
        });
    }
    
    private String extractCaptureIdFromLocation(String location) {
        // Parse "/capture/{captureID}" from location header
        return location.substring(location.lastIndexOf('/') + 1);
    }
}

```

--------------------------------

### List Master Data via GET /bizSteps, /epcs, etc.

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/README.md

Query master data such as business steps, EPCs, and other related entities.

```http
GET /bizSteps, /epcs, ...      → List master data
```

--------------------------------

### Run OpenEPCIS Research Edition with Docker

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Start the Research Edition REST API using Docker Compose. This includes setting up Kafka topics and checking logs.

```shell
docker compose -f docker-compose.rest-api-re.yml up -d

# Run one-time Kafka topic setup
docker compose -f docker-compose.kafka-setup.yml run --rm kafkasetup

# Restart REST API to pick up topics
podman restart quarkus-rest-api-re

# check logs
docker logs --tail 250 -f quarkus-rest-api-re
```

--------------------------------

### Location URN Format Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Illustrates the standard URN format for business locations, specifically using the SGLN scheme.

```plaintext
urn:epc:id:sgln:0012345.11111.400
urn:epc:id:sgln:0012345.22222.0
```

--------------------------------

### Run OpenEPCIS in Developer Mode with Quarkus

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/README.md

Start the OpenEPCIS stack using Docker Compose for dependencies, then run the Community Edition REST API in developer mode with Maven.

```shell
docker compose up -d
docker compose --profile init run --rm kafkasetup

cd distributions/community-edition
mvn quarkus:dev
```

--------------------------------

### Bearer Token Authentication Header

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Example of how to format the Authorization header for Bearer Token authentication.

```http
Authorization: Bearer <token>
```

--------------------------------

### OPTIONS /capture Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

The response to an OPTIONS /capture request includes headers detailing supported methods (Allow) and various limits like GS1-EPCIS-Capture-Limit and GS1-EPCIS-Capture-File-Size-Limit.

```http
HTTP/1.1 204 No Content
Allow: POST, OPTIONS
GS1-EPCIS-Version: 2.0.0
GS1-EPCIS-Capture-Limit: 10000
GS1-EPCIS-Capture-File-Size-Limit: 52428800
```

--------------------------------

### Java EPCIS Workflow Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/INDEX.md

A Java class demonstrating a complete workflow for capturing, querying, and subscribing to EPCIS events using injected clients. Ensure all necessary clients are injected and available.

```java
import java.io.InputStream;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.eclipse.microprofile.reactive.messaging.Message;
import io.smallrye.mutiny.Uni;

import org.eclipse.eas.client.reactive.ReactiveEPCISClient;
import org.eclipse.eas.client.lowlevel.LowLevelEPCISClient;
import org.eclipse.eas.client.websocket.WebSocketClient;

@ApplicationScoped
public class EpcisWorkflow {
    
    @Inject
    ReactiveEPCISClient reactiveClient;
    
    @Inject
    LowLevelEPCISClient epcisClient;
    
    @Inject
    WebSocketClient wsClient;
    
    // 1. Capture events
    public void captureEvents(InputStream events) {
        epcisClient.capture().capturePost(events)
            .subscribe()
            .with(resp -> {
                String jobUrl = resp.getHeaderString("Location");
                System.out.println("Capture job: " + jobUrl);
            });
    }
    
    // 2. Query events
    public void queryEvents() {
        reactiveClient.events(builder -> {
            builder.query().add("EQ_disposition", "in_transit");
            builder.query().add("perPage", "100");
        })
        .subscribe()
        .with(queryDoc -> {
            System.out.println("Found " + queryDoc.getEvents().size() + " events");
        });
    }
    
    // 3. Subscribe to updates
    public void subscribeToUpdates() {
        wsClient.querySubscription("inTransitShipments", event -> {
            System.out.println("New event: " + event.getEventId());
        })
        .subscribe()
        .with(session -> {
            System.out.println("WebSocket connected");
        });
    }
}
```

--------------------------------

### Get Business Steps

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of business steps used in captured events. Supports pagination with perPage and nextPageToken query parameters.

```java
@GET
@Path("/bizSteps")
@Produces({MediaType.APPLICATION_JSON, "application/ld+json", 
           MediaType.APPLICATION_XML, MediaType.TEXT_XML})
public Uni<Response> bizStepsGet(
    @RestQuery(value = "perPage") String perPage,
    @RestQuery(value = "nextPageToken") String nextPageToken)
```

--------------------------------

### Low-Level EPCIS Client Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/INDEX.md

Utilize the low-level client for direct interaction with the Events and Capture APIs. This client uses RestEasy and requires explicit handling of parameters and headers.

```java
@Inject
LowLevelEPCISClient epcisClient;

epcisClient.events().eventsGet(params, headers)
    .subscribe()
    .with(response -> {
        // Handle response
    });
```

--------------------------------

### EPCISQuery Example (JSON)

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/types.md

Defines a named EPCIS query for persistent storage and re-execution. This structure allows for complex queries with parameters.

```json
{
  "queryName": "inTransitShipments",
  "description": "Find all shipments currently in transit",
  "queryLanguage": "simple",
  "queryParameters": {
    "eventType": "ObjectEvent",
    "EQ_bizStep": "shipping",
    "EQ_disposition": "in_transit"
  }
}
```

--------------------------------

### POST /capture Request Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Submit EPCIS events for asynchronous processing. Ensure the Content-Type and GS1-EPCIS-Version headers are correctly set. The request body should be a valid EPCISDocument.

```http
POST /capture HTTP/1.1
Host: localhost:8080
Content-Type: application/json
GS1-Capture-Error-Behaviour: rollback
GS1-EPCIS-Version: 2.0.0

{
  "@context": ["https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"],
  "type": "EPCISDocument",
  "events": [
    {
      "type": "ObjectEvent",
      "eventID": "urn:epc:event:123456",
      "eventTime": "2024-01-15T10:30:00Z",
      "action": "ADD",
      "bizStep": "shipping"
    }
  ]
}
```

--------------------------------

### Restart OpenEPCIS CE REST API with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Restarts the Community Edition REST API container to apply topic configurations. Use this after the Kafka setup.

```shell
podman restart quarkus-rest-api-ce
```

--------------------------------

### Reactive EPCIS Client Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/INDEX.md

Use the reactive client for high-level access to events with automatic pagination. Inject the client and configure query parameters before subscribing to process events.

```java
@Inject
ReactiveEPCISClient reactiveClient;

reactiveClient.events(builder -> {
    builder.query().add("eventType", "ObjectEvent");
    builder.query().add("EQ_bizStep", "shipping");
})
.subscribe()
.with(queryDoc -> {
    queryDoc.getEvents().forEach(event -> {
        System.out.println("Event: " + event.getEventId());
    });
});
```

--------------------------------

### Restart OpenEPCIS RE REST API with Podman

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/docker/README.md

Restarts the Research Edition REST API container to apply topic configurations. Use this after the Kafka setup.

```shell
podman restart quarkus-rest-api-re
```

--------------------------------

### Submit EPCIS Event using curl

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/examples/README.md

Use curl to post an example event directly to the OpenEPCIS capture endpoint. Ensure the Content-Type header is set to application/ld+json.

```bash
curl --header "Content-Type: application/ld+json" --data-binary @example_9.6.1-object_event.jsonld http://localhost:8080/capture
```

--------------------------------

### Example EPC List Response

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

This JSON structure represents a successful response from the GET /epcs endpoint, containing a list of EPCs and the total count.

```json
{
  "epcs": [
    "https://id.gs1.org/01/09506000134352",
    "https://id.gs1.org/01/09506000134353",
    "https://id.gs1.org/01/09506000134354"
  ],
  "totalCount": 1500000
}
```

--------------------------------

### Find ObjectEvents in a Time Window

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-events.md

Retrieve all ObjectEvents that occurred within a specific date and time range. This example uses GET parameters for event type and time boundaries.

```http
GET /events?eventType=ObjectEvent&GE_eventTime=2022-06-30T00:00:00Z&LT_eventTime=2022-07-01T00:00:00Z
```

--------------------------------

### Inject and Use LowLevelEPCISClient

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-low-level.md

Demonstrates how to inject the LowLevelEPCISClient and use it to submit events.

```java
import jakarta.inject.Inject;

// ...

@Inject
LowLevelEPCISClient epcisClient;

// Use in service
public void submitEvents() {
    epcisClient.capture().capturePost(eventStream);
}
```

--------------------------------

### 401 Unauthorized Error Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of an authentication error response when credentials are missing, invalid, or expired.

```json
{
  "type": "urn:epcis:error:authentication",
  "title": "Unauthorized",
  "detail": "Missing or invalid authentication credentials",
  "status": 401
}
```

--------------------------------

### 406 Not Acceptable Error Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of a not acceptable error response when the requested content type is not supported by the server.

```json
{
  "type": "urn:epcis:error:notacceptable",
  "title": "Not Acceptable",
  "detail": "Content-Type 'text/csv' is not supported. Supported: application/json, application/ld+json, application/xml",
  "status": 406
}
```

--------------------------------

### List Named Queries with Pagination and Version Filtering

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-queries.md

Demonstrates how to list all available named queries using the `queriesGet` method. It includes pagination parameters (`perPage`, `nextPageToken`) and version filtering headers (`GS1-CBV-Min`, `GS1-CBV-Max`, `GS1-EPCIS-Min`, `GS1-EPCIS-Max`). The example shows how to subscribe to the response and process the list of queries.

```java
QueryApi queryApi = /* injected */;

Uni<Response> response = queryApi.queriesGet(
    null,  // nextPageToken
    "50",  // perPage
    "2.0.0",  // cbvMin
    "2.0.0",  // cbvMax
    "2.0.0",  // epcisMin
    "2.0.0"   // epcisMax
);

response.subscribe().with(resp -> {
    if (resp.getStatus() == 200) {
        JsonObject listDoc = resp.readEntity(JsonObject.class);
        JsonArray queries = listDoc.getJsonArray("queries");
        
        queries.forEach(q -> {
            JsonObject query = (JsonObject) q;
            System.out.println("Query: " + query.getString("queryName"));
        });
    }
});
```

--------------------------------

### 403 Forbidden Error Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of an authorization error response when a client is authenticated but lacks the necessary permissions.

```json
{
  "type": "urn:epcis:error:authorization",
  "title": "Forbidden",
  "detail": "Client role 'reader' does not permit capture operations",
  "status": 403
}
```

--------------------------------

### Get Specific Event via GET /events/{eventID}

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/README.md

Fetch a single EPCIS event by its unique event ID.

```http
GET /events/{eventID}          → Get specific event
```

--------------------------------

### Read Point URN Format Examples

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Examples of Uniform Resource Names (URNs) used to identify read points in the EPCIS system.

```text
urn:epc:id:sgln:0012345.11111.400
urn:epc:id:sscc:0012345.123456789
```

--------------------------------

### 400 Bad Request Error Response Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of a validation error response for a malformed request, invalid query parameters, or invalid body.

```json
{
  "type": "urn:epcis:error:validation",
  "title": "Validation Error",
  "detail": "Query parameter 'eventType' has invalid value: 'InvalidEvent'",
  "status": 400
}
```

--------------------------------

### Create Native Executable

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/modules/openepcis-generated-events-capture/README.md

Build a native executable of the application using this Maven command. For builds within a container, use the `-Dquarkus.native.container-build=true` flag.

```shell
./mvnw package -Dnative
```

```shell
./mvnw package -Dnative -Dquarkus.native.container-build=true
```

--------------------------------

### GET /readPoints Endpoint Signature

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

This Java method signature defines the GET /readPoints endpoint, which returns read points where events were observed. It accepts optional pagination parameters.

```java
@GET
@Path("/readPoints")
@Produces({MediaType.APPLICATION_JSON, "application/ld+json", 
           MediaType.APPLICATION_XML, MediaType.TEXT_XML})
public Uni<Response> readPointsGet(
    @RestQuery(value = "perPage") String perPage,
    @RestQuery(value = "nextPageToken") String nextPageToken)
```

--------------------------------

### GET /dispositions Endpoint Signature

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

This Java method signature defines the GET /dispositions endpoint, which returns disposition values used in captured events. It accepts optional pagination parameters.

```java
@GET
@Path("/dispositions")
@Produces({MediaType.APPLICATION_JSON, "application/ld+json", 
           MediaType.APPLICATION_XML, MediaType.TEXT_XML})
public Uni<Response> dispositionsGet(
    @RestQuery(value = "perPage") String perPage,
    @RestQuery(value = "nextPageToken") String nextPageToken)
```

--------------------------------

### GET /readPoints

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of read points where events have been observed. Supports pagination.

```APIDOC
## GET /readPoints

### Description
Returns read points where events were observed. This endpoint supports pagination through `perPage` and `nextPageToken` query parameters.

### Method
GET

### Endpoint
/readPoints

### Parameters
#### Query Parameters
- **perPage** (string) - Optional - The number of read points to return per page.
- **nextPageToken** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **readPoints** (array) - Array of read point URNs.

### Response Example
```json
{
  "readPoints": [
    "urn:epc:id:sgln:0012345.11111.400",
    "urn:epc:id:sscc:0012345.123456789"
  ]
}
```
```

--------------------------------

### GET /dispositions

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of disposition values used in captured events. Supports pagination.

```APIDOC
## GET /dispositions

### Description
Returns disposition values used in captured events. This endpoint supports pagination through `perPage` and `nextPageToken` query parameters.

### Method
GET

### Endpoint
/dispositions

### Parameters
#### Query Parameters
- **perPage** (string) - Optional - The number of dispositions to return per page.
- **nextPageToken** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **dispositions** (array) - Array of disposition names.

### Response Example
```json
{
  "dispositions": [
    "in_transit",
    "no_pedigree_flag",
    "completeness_verified",
    "completeness_suspicious",
    "all_data_present"
  ]
}
```
```

--------------------------------

### Run Application in Dev Mode

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/modules/openepcis-generated-events-capture/README.md

Execute this command to run the application in development mode, enabling live coding. Access the Dev UI at http://localhost:8080/q/dev/.

```shell
./mvnw compile quarkus:dev
```

--------------------------------

### Query All Events via GET /events

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/README.md

Retrieve a collection of all EPCIS events stored in the repository.

```http
GET /events                    → Query all events
```

--------------------------------

### GET /queries

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-queries.md

Lists all named queries available to the authenticated client. Supports pagination through `perPage` and `nextPageToken`.

```APIDOC
## GET /queries

### Description
Lists all named queries available to the authenticated client. Supports pagination through `perPage` and `nextPageToken`.

### Method
GET

### Endpoint
/queries

### Parameters
#### Query Parameters
- **nextPageToken** (string) - Optional - Token for fetching the next page
- **perPage** (integer) - Optional - Number of queries per page (Default: 30)

#### Headers (Request)
- **GS1-CBV-Min** (string) - Optional - Minimum supported CBV version
- **GS1-CBV-Max** (string) - Optional - Maximum supported CBV version
- **GS1-EPCIS-Min** (string) - Optional - Minimum supported EPCIS version
- **GS1-EPCIS-Max** (string) - Optional - Maximum supported EPCIS version

### Response
#### Success Response (200 OK)
- **queries** (array) - Array of query metadata objects
- **nextPageToken** (string) - Token for next page if applicable

Query Metadata Object:
- **queryName** (string) - Unique name of the query
- **description** (string) - User-provided description
- **createdTime** (timestamp) - When the query was created
- **lastModifiedTime** (timestamp) - When the query was last modified
- **queryUri** (string) - URI reference to the query resource
- **queryDefinition** (object) - EPCIS query definition

#### Error Responses
- **400 Bad Request**: Invalid pagination parameters.
- **401 Unauthorized**: Missing or invalid authorization.
- **403 Forbidden**: Client not authorized to list queries.
- **500 Internal Server Error**: Server error retrieving query list.

### Request Example
```java
QueryApi queryApi = /* injected */;

Uni<Response> response = queryApi.queriesGet(
    null,  // nextPageToken
    "50",  // perPage
    "2.0.0",  // cbvMin
    "2.0.0",  // cbvMax
    "2.0.0",  // epcisMin
    "2.0.0"   // epcisMax
);

response.subscribe().with(resp -> {
    if (resp.getStatus() == 200) {
        JsonObject listDoc = resp.readEntity(JsonObject.class);
        JsonArray queries = listDoc.getJsonArray("queries");
        
        queries.forEach(q -> {
            JsonObject query = (JsonObject) q;
            System.out.println("Query: " + query.getString("queryName"));
        });
    }
});
```
```

--------------------------------

### Error Response Structure

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Example of a JSON response indicating a validation error due to an invalid query parameter.

```json
{
  "type": "urn:epcis:error:validation",
  "detail": "Invalid timestamp format in GE_eventTime: 'invalid-timestamp'",
  "status": 400
}
```

--------------------------------

### Repository Structure

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/INDEX.md

Overview of the directory structure for the OpenEPCIS repository.

```bash
modules/
├── openepcis-client/               # Java client libraries
├── openepcis-rest-api-common/      # Shared REST API interfaces
├── openepcis-generated-events-capture/  # Test data generator
├── quarkus-capture-topology-ce/    # Kafka event processing
└── quarkus-rest-application-ce/    # REST API server
```

--------------------------------

### Invalid Query Parameter Example

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/errors.md

Demonstrates an invalid timestamp format in a query parameter, leading to a validation error.

```http
GET /events?GE_eventTime=invalid-timestamp
```

--------------------------------

### GET /epcs

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of Electronic Product Codes (EPCs) captured in the repository. Supports pagination through query parameters.

```APIDOC
## GET /epcs

### Description
Returns Electronic Product Codes (EPCs) that have been captured in the repository. This endpoint supports pagination.

### Method
GET

### Endpoint
/epcs

### Parameters
#### Query Parameters
- **perPage** (integer) - Optional - Results per page. Defaults to 30.
- **nextPageToken** (string) - Optional - Pagination token for retrieving the next set of results.

### Response
#### Success Response (200 OK)
- **epcs** (array) - Array of EPC strings (GS1 Digital Link format).
- **nextPageToken** (string) - Token for the next page, if applicable.
- **totalCount** (integer) - Total number of EPCs in the repository.

#### Response Example
```json
{
  "epcs": [
    "https://id.gs1.org/01/09506000134352",
    "https://id.gs1.org/01/09506000134353",
    "https://id.gs1.org/01/09506000134354"
  ],
  "totalCount": 1500000
}
```
```

--------------------------------

### Discover All Business Steps

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves all business steps in use, limited to 1000 results. Useful for understanding vocabulary across events.

```java
// Get all business steps in use
eventsApi.bizStepsGet("1000", null)
    .subscribe()
    .with(resp -> {
        JsonArray steps = resp.readEntity(JsonObject.class)
            .getJsonArray("bizSteps");
        System.out.println("Using " + steps.size() + " business steps");
    });
```

--------------------------------

### List Event Types via GET /eventTypes

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/README.md

Retrieve a list of all available EPCIS event types supported by the repository.

```http
GET /eventTypes                → List event types
```

--------------------------------

### Configure Authentication for EPCIS Client

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-low-level.md

Set up authentication using either Basic Auth or API Key by configuring properties in application.properties. The client automatically handles these headers.

```properties
# Basic authentication
openepcis-client.username=myuser
openepcis-client.password=mypass

# OR API key authentication
openepcis-client.api-key=my-api-key
openepcis-client.api-key-secret=my-api-secret
```

--------------------------------

### Get Event Types

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of all available event types from the repository. Supports pagination with `perPage` and `nextPageToken` query parameters.

```java
@GET
@Path("/eventTypes")
@Produces({MediaType.APPLICATION_JSON, "application/ld+json", 
           MediaType.APPLICATION_XML, MediaType.TEXT_XML})
public Uni<Response> eventTypesGet()
```

```json
{
  "eventTypes": [
    "ObjectEvent",
    "AggregationEvent",
    "TransactionEvent",
    "TransformationEvent",
    "AssociationEvent"
  ],
  "totalCount": 5
}
```

--------------------------------

### Activate Production Profile via JVM Argument

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/configuration.md

Activates the 'prod' profile by setting the quarkus.profile system property when running the application.

```bash
java -Dquarkus.profile=prod -jar application.jar
```

--------------------------------

### ReactiveEPCISClient Usage

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-reactive.md

Demonstrates how to inject and use the `ReactiveEPCISClient` for querying EPCIS events.

```APIDOC
## Dependency Injection

```java
@Inject
ReactiveEPCISClient reactiveClient;

// Or via constructor
public MyService(ReactiveEPCISClient client) {
    this.client = client;
}
```
```

--------------------------------

### Business Vocabulary URN Formats

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/types.md

Business vocabularies are represented using the URN format. Examples include specific business steps and dispositions.

```text
urn:epc:id:sgln:0012345.11111.400
```

```text
urn:epc:cbv:bizstep:shipping
```

```text
urn:epc:cbv:disp:in_transit
```

--------------------------------

### Get Capture Job Status

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Retrieve the status of an asynchronous capture job using its unique ID. Handles success and not found scenarios.

```http
GET /capture/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: localhost:8080
```

```json
{
  "captureID": "550e8400-e29b-41d4-a716-446655440000",
  "running": false,
  "success": true,
  "captureErrorBehaviour": "rollback",
  "totalEvents": 100,
  "capturedEvents": 100,
  "failedEvents": 0
}
```

```json
{
  "type": "urn:epcis:error:notfound",
  "title": "Not Found",
  "detail": "Capture job not found",
  "status": 404
}
```

--------------------------------

### Basic WebSocket Subscription

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-websocket.md

Establishes a WebSocket connection for a named query subscription and logs received events. Includes session connection and error handling.

```java
@Inject
WebSocketClient wsClient;

public void subscribeToShipments() {
    wsClient.querySubscription("inTransitShipments", event -> {
        System.out.println("New event received: " + event.getEventId());
        System.out.println("Business step: " + event.getBusinessStep());
    })
    .subscribe()
    .with(
        session -> {
            System.out.println("WebSocket connected, session: " + session.getId());
        },
        error -> {
            System.err.println("Failed to establish WebSocket: " + error.getMessage());
        }
    );
}
```

--------------------------------

### Inject and Use WebSocketClient

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/java-client-websocket.md

Demonstrates how to inject and use the WebSocketClient for subscribing to query results. The callback function processes incoming events.

```java
@Inject
WebSocketClient wsClient;

public void subscribeToEvents(String queryName) {
    wsClient.querySubscription(queryName, event -> {
        System.out.println("New event: " + event);
    });
}
```

--------------------------------

### Get Business Locations

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Retrieves a list of business locations referenced in captured events. Supports pagination with perPage and nextPageToken query parameters.

```java
@GET
@Path("/bizLocations")
@Produces({MediaType.APPLICATION_JSON, "application/ld+json", 
           MediaType.APPLICATION_XML, MediaType.TEXT_XML})
public Uni<Response> bizLocationsGet(
    @RestQuery(value = "perPage") String perPage,
    @RestQuery(value = "nextPageToken") String nextPageToken)
```

--------------------------------

### Monitor Capture Job via GET /capture/{captureID}

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/README.md

Retrieve the status of an event capture job using its unique capture ID.

```http
GET  /capture/{captureID}  → Monitor capture job
```

--------------------------------

### List Business Steps

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Retrieves a paginated list of business steps. Supports pagination via `perPage` and `nextPageToken` query parameters.

```json
{
  "bizSteps": [
    "shipping",
    "receiving",
    "packing",
    "manufacturing"
  ]
}
```

--------------------------------

### Package Application as Uber-Jar

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/modules/openepcis-generated-events-capture/README.md

Use this command to package the application as an uber-jar for execution. The packaged application can be run using `java -jar target/*-runner.jar`.

```shell
./mvnw package -Dquarkus.package.jar.type=uber-jar
```

--------------------------------

### List Business Steps

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/endpoints.md

Retrieves a paginated list of predefined business step values.

```APIDOC
## GET /bizSteps

### Description
List business steps.

### Method
GET

### Endpoint
/bizSteps

### Parameters
#### Query Parameters
- **perPage** (integer) - Optional - Number of business steps to return per page.
- **nextPageToken** (string) - Optional - Token for the next page of results.
```

--------------------------------

### ProblemResponseBody Example (JSON)

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/types.md

Illustrates the structure of an error response conforming to RFC 7807 Problem Details for HTTP APIs. Use this for all error responses.

```json
{
  "type": "urn:epcis:error:validation",
  "title": "Validation Error",
  "detail": "Event at index 2 is missing required field 'eventTime'",
  "instance": "/capture/550e8400-e29b-41d4-a716-446655440000",
  "status": 400
}
```

--------------------------------

### Polling Strategy for Capture Job Completion

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-capture-jobs.md

Example Java code demonstrating how to poll for the completion status of a capture job using exponential backoff.

```APIDOC
## Polling Strategy

For monitoring capture job completion:

```java
// Poll strategy with exponential backoff
UUID captureID = /* from 202 response Location header */;
int pollIntervalMs = 100;
int maxPolls = 600;  // 60 seconds max

for (int i = 0; i < maxPolls; i++) {
    Thread.sleep(pollIntervalMs);
    
    Response jobStatus = captureJobApi.captureGet(captureID, null, null, null)
        .await().indefinitely();
    
    JsonObject body = jobStatus.readEntity(JsonObject.class);
    boolean running = body.getBoolean("running");
    
    if (!running) {
        boolean success = body.getBoolean("success");
        System.out.println("Capture complete: " + (success ? "SUCCESS" : "FAILURE"));
        break;
    }
    
    // Increase poll interval (e.g., cap at 1 second)
    pollIntervalMs = Math.min(pollIntervalMs * 2, 1000);
}
```
```

--------------------------------

### Autocomplete UI for Business Steps

Source: https://github.com/openepcis/epcis-repository-ce/blob/main/_autodocs/api-reference/rest-api-toplevel-resources.md

Fetches business steps for UI autocomplete suggestions, limiting results to 100. The retrieved steps are passed to a UI update function.

```java
// UI autocomplete for business steps
eventsApi.bizStepsGet("100", null)
    .subscribe()
    .with(resp -> {
        JsonArray steps = resp.readEntity(JsonObject.class)
            .getJsonArray("bizSteps");
        // Pass to UI for autocomplete
        updateStepSuggestions(steps);
    });
```