Use Management API v4 across all samples and tests

[mokhairymahmoud]

Problem Statement

The EDC Samples repository currently uses Management API v3 throughout its system tests, README documentation, and curl examples. As of EDC 0.17.0, v4 is stable and v3 is deprecated. Developers following the samples are exposed to deprecated API paths, which leads to confusion and will break in a future EDC release when v3 is removed.

Solution

Migrate every occurrence of the Management API from /v3/ to /v4/ across all sample modules: system test Java code, README documentation, and curl request examples. For the consumer-pull sample (transfer-03), the /v3/edrs/{id}/dataaddress endpoint was removed in v4 (the EDR cache was deprecated in 0.17.0), so that test must be reworked to reflect the new data-plane flow without the EDR cache.

User Stories

1. As a developer following the transfer-01-negotiation sample, I want the curl commands in the README to use /v4/ paths, so that my requests succeed against EDC 0.17.0+ without deprecation warnings.
2. As a developer following the transfer-02-provider-push sample, I want the README curl examples to reference the stable v4 Management API, so that I am not misled into using a deprecated interface.
3. As a developer following the transfer-03-consumer-pull sample, I want the README and test to reflect the current consumer-pull flow that works with EDC 0.17.0, so that I can reproduce the sample successfully.
4. As a developer following the transfer-04-event-consumer sample, I want the README curl commands to use v4 Management API paths, so that I can run the sample against the current EDC version.
5. As a developer following the transfer-05-file-transfer-cloud sample, I want all API calls in the README to reference v4, so that my cloud transfer setup is not built on deprecated endpoints.
6. As a developer following the transfer-06-kafka-broker sample, I want the README curl examples to use the v4 Management API, so that my Kafka-based transfer setup uses the stable API.
7. As a developer following the policy-01-policy-enforcement sample, I want the README curl commands to call /v4/ endpoints, so that my policy tests work correctly with current EDC.
8. As a developer following the advanced-01-open-telemetry sample, I want the README examples to use Management API v4, so that the observability walkthrough matches a supported runtime.
9. As a developer following any federated catalog sample, I want both the README and test code to use /v4/catalogs/request, so that my federated catalog queries work against EDC 0.17.0+.
10. As a contributor running the system test suite, I want NegotiationCommon.java to call /v4/assets, /v4/policydefinitions, /v4/contractdefinitions, /v4/catalog/dataset/request, and /v4/contractnegotiations/, so that automated tests pass against the current EDC dependency.
11. As a contributor running the system test suite, I want TransferUtil.java to call /v4/transferprocesses/, so that transfer process polling and initiation work correctly.
12. As a contributor running the system test suite, I want PolicyCommon.java to call all provider-side setup endpoints on /v4/, so that policy enforcement tests are not relying on deprecated paths.
13. As a contributor running the system test suite, I want FederatedCatalogCommon.java to call /v4/catalogs/request for both the embedded and standalone federated catalog runtimes, so that federated catalog tests work with the current API.
14. As a contributor, I want stale variable names in NegotiationCommon.java (e.g., V2_POLICY_DEFINITIONS_PATH, V2_CONTRACT_DEFINITIONS_PATH) that reference v2 but point to v3 paths to be renamed to reflect the actual version (v4), so that the code is not misleading.
15. As a maintainer, I want the consumer-pull test (Transfer03httpProxyConsumerPullTest) to be updated or clearly documented regarding the removal of the EDR cache in v4, so that no test silently calls a removed endpoint.
16. As a maintainer, I want all Management API version constants in Java files to be centralised or clearly named so that future version bumps are easy to find and update.

Implementation Decisions

• All /v3/ paths → /v4/: Every hardcoded /v3/ segment in system test helper classes and README curl examples must be changed to /v4/. This affects NegotiationCommon, TransferUtil, PolicyCommon, FederatedCatalogCommon, and Transfer03httpProxyConsumerPullTest.
• Renamed string constants: Constants in NegotiationCommon currently named with a V2_ prefix (historical artifact) but pointing to v3 paths should be renamed to V4_ to match the new target path.
• Federated catalog endpoint: The federated catalog API is versioned the same way; /v3/catalogs/request becomes /v4/catalogs/request. This is now served under the management context as of 0.17.0.
• EDR cache removed in v4: The /v3/edrs/{id}/dataaddress endpoint has no v4 equivalent — the EDR cache was deprecated in EDC 0.17.0. The Transfer03httpProxyConsumerPullTest and the transfer-03 README curl step that calls this endpoint must be updated. The recommended approach is to replace the EDR lookup with the equivalent flow for the new Data Plane Signaling (DPS) path, or remove that step if the sample's purpose can be demonstrated without it.
• README files: All twelve README files that contain /management/v3/ in curl commands must be updated to /management/v4/. No README restructuring is needed — only the version segment in URLs changes.
• No JSON body changes expected: The v4 Management API uses the same JSON-LD request/response bodies as v3 for assets, policies, contract definitions, catalog requests, negotiations, and transfer processes. Body payloads in the resources/ directories should not need modification, but should be validated against the v4 OpenAPI spec during implementation.

Testing Decisions

• What makes a good test here: Tests should verify the observable, external behaviour of the sample — a full end-to-end run that creates assets, negotiates contracts, starts transfers, and asserts outcomes. They should not test internal HTTP helper implementations.
• Modules to exercise: All existing end-to-end system tests under system-tests/ should continue to pass after the migration. No new test classes are required; this is purely a migration of existing test infrastructure.
• Prior art: The existing Transfer01NegotiationSampleTest, Transfer02ProviderPushSampleTest, Transfer03httpProxyConsumerPullTest, Transfer04EventConsumerTest, Policy01PolicyEnforcementTest, and the federated catalog tests are the reference baseline. They should all pass unmodified (except for the v3→v4 path changes within them).
• Transfer-03 special case: Before the migration is marked complete, the consumer-pull test must either pass end-to-end with the new DPS-based flow or be accompanied by a documented explanation of what changed and why the EDR step was removed.

Out of Scope

• Migrating to Management API v5 (currently in beta/alpha as of EDC 0.17.0).
• Changes to DSP (Dataspace Protocol) endpoint paths (e.g., /protocol/2025-1) — those are not part of the Management API versioning.
• Changes to the basic/ samples (they do not call the Management API directly in tests).
• Introducing a new sample that demonstrates Management API v4-specific features.
• Updating Postman collections, if any exist outside this repository.

Further Notes

• EDC 0.17.0 release notes confirm: "management-api stabilize V4, deprecate V3, promote V5 beta" (PR #5668 in eclipse-edc/Connector).
• The EDR cache deprecation note in PR #5668 states: "got rid of some HTTP-Pull E2E tests as they were relying on the EDR cache that has been removed in v4" — the transfer-03 consumer-pull scenario will need the most investigation.
• Closes Use management v4 #531.

[github-actions]

Thanks for your contribution 🔥 We will take a look asap 🚀

[mokhairymahmoud]

Closing — PRD will be managed locally instead.