Skip to content

Ingestion API

Overview

The Ingestion API facilitates seamless integration of data into the Circulor PROVE system, offering a structured approach to managing product information at various levels. This API supports a comprehensive data model encompassing high-level product definitions, individual product instances, and their traceability throughout the supply chain.

Product data is structured into three distinct hierarchical levels, each serving a specific function:

dpp-overview

Product (Static Data)

  • Represents foundational, immutable attributes of a product type.
  • Includes details such as product name, category, manufacturer, and general specifications.
  • Serves as a template for all individual product items of the same type.

Product Item

  • Corresponds to specific instances or units of a product.
  • Contains static attributes unique to the item, such as serial number, production date, and production location.
  • May also include dynamic attributes that evolve over time, such as state of charge or location.

Traceability

  • Tracks the lifecycle and transformations of a product item throughout the supply chain.
  • Captures details on material sourcing, manufacturing processes, and distribution.
  • Establishes provenance and ensures authenticity by maintaining a complete historical record of each product item.

Data Hierarchy

The API enforces a hierarchical structure to ensure data integrity and traceability:

  • Product: Linked to a specific customer, allowing for customized product definitions.
  • Product Item: Associated with a product type, inheriting static characteristics while maintaining unique, item-specific data.
  • Traceability: Attached to individual product items, providing a complete record of their origin and journey.

Authentication

The API employs OAuth2 for secure authentication and authorization. Credentials are provided by our support team upon request.

For detailed authentication guidelines, refer to the Authentication documentation.

Product Data API

The Product Data API enables management of product definitions and details, supporting various operations to create, update, and retrieve products and individual items.

For more information, refer to the Product documentation.

Traceability Data API

The Traceability Data API offers endpoints to manage traceability records, ensuring comprehensive tracking of product items throughout their lifecycle.

For further details, see the Traceability documentation.

Service Levels

This section outlines the expected performance characteristics of the Ingestion API.

The Ingestion API operates on an asynchronous processing model. Upon submission, product and traceability data is validated and queued for background processing. While the initial API response acknowledges the request, the final processing time may vary. Clients can monitor the status of an ingestion request via the relevant status endpoint.

Throughput

The Ingestion API is configured with throttling limits to ensure stability and fair usage. The limits are based on a token bucket model, which defines a steady-state rate and a burst capacity for incoming requests.

  • Rate Limit: The API supports a sustained rate of 10 requests per second (RPS), which is equivalent to 600 requests per minute.
  • Burst Capacity: The system can handle a burst of up to 20 concurrent requests.

These throttling limits are applied on a best-effort basis and should be considered as target ceilings rather than guaranteed request capacities. If the limits are exceeded, the API will respond with an HTTP 429 Too Many Requests status code.

While the API supports batching multiple data items into a single request, specific performance metrics for batch operations are not yet defined. Utilizing batching can be an effective strategy to stay within the rate limits when dealing with high volumes of data.

Authentication Rate Limiting

In addition to API request throttling, the authentication service imposes its own rate limits to prevent abuse. A limit of 100 token requests per 5-minute interval is enforced for each IP address. If this limit is exceeded, subsequent token requests from that IP address will be temporarily blocked until the restriction period expires.

Response Times

Based on performance monitoring, the API typically exhibits the following response time characteristics:

  • Average Latency: The average response time is approximately 360 ms.

The provided latency metrics represent blended averages across all API endpoints and do not correspond to a specific operation. These figures are influenced by a variety of factors, including system load and the size of the request payload, which can include large batch operations containing thousands of traceability events. As such, they should be considered indicative rather than absolute.