Documentation
¶
Overview ¶
Package api provides HTTP endpoints for interacting with the Digital Product Passport registry. It defines RESTful routes for creating, retrieving, and verifying DPP records, as well as accessing blockchain transaction information.
Index ¶
Constants ¶
This section is empty.
Variables ¶
PeerNode is the global peer node instance shared across all API handlers. It provides access to the blockchain functionality and must be initialized via SetPeerNode() before any API handlers are called, otherwise requests will fail with "blockchain service not initialized" errors.
Functions ¶
func CreateRecord ¶
CreateRecord handles POST /records requests.
This endpoint creates a new Digital Product Passport record or updates an existing one. It determines whether the operation is an update by checking if a record with the same GTIN14+lot+serial already exists. The response includes different status codes for creation (201) vs. update (200) operations.
Request Body: JSON object containing Record fields
- Provider: (required) The DPP provider/authority name
- UUID: (required) Unique identifier within the provider's system
- GTIN14: (required) Global Trade Item Number (14 digits)
- Lot: (optional) Identifies a specific production batch
- Serial: (optional) Uniquely identifies an individual item
Responses:
- 201 Created: New record was successfully created
- 200 OK: Existing record was successfully updated
- 400 Bad Request: Missing required fields or invalid data
- 500 Internal Server Error: If the blockchain service is not initialized
func GetRecord ¶
GetRecord handles GET /records?provider=...&serial=... requests.
This endpoint retrieves a specific Digital Product Passport record by its provider and serial number. This is different from the GTIN-based lookup as it directly uses the internal record key rather than product identifiers.
Query Parameters:
- provider: The DPP provider/authority name
- serial: The serial number assigned by the provider
Responses:
- 200 OK: Complete record with all fields (Provider, UUID, GTIN14, Lot, Serial)
- 404 Not Found: No record matches the specified provider and serial
- 500 Internal Server Error: If the blockchain service is not initialized
func GetRecordByGTIN ¶
GetRecordByGTIN handles GET /records/gtin/:gtin?lot=...&serial=... requests.
This endpoint allows discovering Digital Product Passport locations (provider+UUID) using product identification criteria. It searches for records matching the specified GTIN14 and optional lot and serial parameters.
Path Parameters:
- gtin: The Global Trade Item Number (14 digits) to search for
Query Parameters:
- lot: Optional lot/batch number to narrow the search
- serial: Optional serial number to narrow the search
Responses:
- 200 OK: List of matching records with their provider and UUID
- 404 Not Found: No records match the search criteria
- 500 Internal Server Error: If the blockchain service is not initialized or search fails
func GetRecordHistoryByGTIN ¶
GetRecordHistoryByGTIN handles GET /records/gtin/:gtin/history?lot=...&serial=... requests.
This endpoint retrieves the complete transaction history for all records matching the specified GTIN14 and optional lot and serial parameters. It allows for tracking all changes made to the Digital Product Passport(s) for a particular product.
Path Parameters:
- gtin: The Global Trade Item Number (14 digits) to search for
Query Parameters:
- lot: Optional lot/batch number to narrow the search
- serial: Optional serial number to narrow the search
Responses:
- 200 OK: Map of record keys to their transaction histories in chronological order
- 500 Internal Server Error: If the blockchain service is not initialized or history retrieval fails
func NewRouter ¶
NewRouter creates and returns a Gin engine with all API routes defined but without a connected peer node. This is typically used for testing and requires setting the peer node separately using SetPeerNode() before handling requests.
Defined routes include: - GET /records - Retrieve a record by provider and serial - GET /records/gtin/:gtin - Find records matching a GTIN14 - GET /records/gtin/:gtin/history - Get history of records matching a GTIN14 - POST /records - Create or update a record
Returns a configured gin.Engine instance ready to serve HTTP requests.
func NewRouterWithPeer ¶
NewRouterWithPeer creates and returns a Gin engine with all API routes defined and connected to the specified peer node. This is the preferred way to initialize the API for production use as it automatically sets up the peer node for all handlers.
In addition to the standard record routes, this also configures blockchain-specific routes: - GET /blockchain/transaction/:id - Get details about a specific transaction - GET /blockchain/record/:key/history - Get transaction history for a specific record - GET /blockchain/record/:key/verify - Verify a record's existence on the blockchain
Parameters:
- peer: A fully initialized node.Peer instance connected to a blockchain
Returns a configured gin.Engine instance ready to serve HTTP requests.
func SetPeerNode ¶
SetPeerNode sets the global peer node instance for use by all API handlers.
This function must be called to initialize the PeerNode variable before any API handlers are invoked, typically during application startup or when the router is created using NewRouterWithPeer().
Parameters:
- peer: A fully initialized node.Peer instance connected to a blockchain
Types ¶
This section is empty.
Source Files
¶
- handlers.go
- router.go