Use project handle as gateway.api-platform.wso2.com/project-id annotation

[thivindu]

Summary

This PR resolve project-scoped artifacts by project handle, not display name

Resolves: #2678

Problem

When a project-scoped artifact (LLM Proxy, MCP Proxy, REST API) is pushed from the gateway to the control plane, the owning project is conveyed via the gateway.api-platform.wso2.com/project-id annotation. Per the platform's "CRs carry handles" design, this annotation carries the project handle — but the DP→CP import path resolved it against the project display name (GetProjectByNameAndOrgID).

As a result, a push with the correct handle (project-id: default) failed with ProjectNotFound, while a push using the display name (Default) coincidentally succeeded. This blocked bottom-up creation of any project-scoped artifact.

Approach

• ArtifactImportService now resolves the owning project via GetProjectByHandleAndOrgID, so the annotation is interpreted as the project handle. This is the single, shared resolution point, so the fix applies uniformly to all project-scoped kinds (REST API, LLM Proxy, MCP Proxy).
• Renamed the internal ImportContext.ProjectName field to ProjectHandle and updated ResolveImportProject docs/log messages to reflect that the value is a handle, not a display name.

Examples

• Added the gateway.api-platform.wso2.com/project-id: default annotation to every project-scoped example that was missing it (anthropic-openai-proxy, azure-openai-proxy, mistral-openai-proxy, openai-multi-provider-proxy, basic-ratelimit-demo-api, sample-echo-api).
• Updated petstore-api.yaml to use the default handle instead of a project UUID, and corrected llm-proxy.yaml / mcp-proxy.yaml from the display name Default to the handle default.

Behaviour change

The project-id annotation must now be the project handle. A value matching only the display name (that isn't also the handle) will no longer resolve — this is the intended contract.

[coderabbitai]

📝 Walkthrough

Walkthrough

Gateway examples now carry normalized project annotations. Artifact import context and project resolution use project handles, with regression coverage confirming display names are rejected and handles resolve successfully.

Changes

Project Handle Import Resolution

Layer / File(s)	Summary
Project handle contract platform-api/internal/service/artifact_import.go, platform-api/internal/utils/import_artifacts.go	Import context naming and project annotation handling now use ProjectHandle, while annotation-first resolution and legacy fallback remain unchanged.
Handle-based project lookup platform-api/internal/service/artifact_import.go	Project-scoped imports require a handle and resolve projects with GetProjectByHandleAndOrgID; missing-project errors reference the handle.
Validation and example alignment platform-api/internal/service/artifact_import_test.go, gateway/examples/*	Tests distinguish project handles from display names, and example manifests add or normalize the project annotation values.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description covers the core fix, but it is missing several template sections like Goals, Tests, Security checks, Related PRs, and Test environment.	Add the missing template sections or mark them N/A, including Goals, User stories, Documentation, Automation tests, Security checks, Related PRs, and Test environment.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: project-scoped imports now use the project handle in the annotation.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Thushani-Jayasekera]

approved since this is a platform api change

[Thushani-Jayasekera]

blocking merging temporally