@nospt/backstage-plugin-apigee-backend

Backend package for the bootstrap stage of the Backstage Apigee plugin.

Included

• New Backend System plugin registration
• Minimal router mounted at /api/apigee
• Placeholder health endpoint at /api/apigee/health

Development

cd plugins/apigee-backend
yarn start
yarn test
yarn lint
yarn build

Repository Stitching

A Backstage CatalogProcessor (ApigeeStitchingProcessor) links a backend Component to its proxy API entity by emitting the native providesApi / apiProvidedBy relations. This surfaces the standard "Provided APIs" card on the component page and the "Providers" card on the API page — with zero custom UI. A repository opts in by adding nos.pt/apigee-* annotations to its catalog-info.yaml.

Annotation styles

Direct mapping (active in this release):

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-service
  annotations:
    nos.pt/apigee-api-name: my-proxy
    nos.pt/apigee-project-id: apigee-x-public-p-123
spec:
  type: service
  owner: team-orders
  lifecycle: production

TargetServer-based mapping (documented; resolution planned, not yet active):

metadata:
  annotations:
    nos.pt/apigee-targetserver-hostname: backend.nos.pt
    nos.pt/apigee-targetserver-port: "443"

Precedence rule

When both styles are present, the TargetServer-based mapping is the preferred resolution path (STITCH-02). The direct API-name mapping is the fallback, used when no TargetServer annotation is present or when TargetServer resolution is ambiguous (for example, a generic load balancer shared by many proxies).

In this release only the direct-mapping path is implemented. TargetServer resolution is planned but not yet active — no TargetServer data is captured by the entity provider yet (see 04-CONTEXT D-01). The processor is structured around a resolution-strategy seam so the TargetServer branch slots in without rework.

Apigee → Backstage mapping

| Apigee concept | Backstage entity | |----------------|------------------| | API proxy (implementation) | kind: Component, spec.type: api-proxy | | API proxy (contract) | kind: API, spec.type from API Hub (default other) | | Sharedflow | kind: Component, spec.type: library | | Backend repo component ↔ proxy API | providesApi / apiProvidedBy relation |

Resolution detail

The target API entity ref is deterministic: api:default/<slugify(nos.pt/apigee-api-name)>. The processor reads the annotations, synthesizes the ref, and emits the relation pair — no live catalog lookup is needed. A partial annotation set (e.g. nos.pt/apigee-api-name without nos.pt/apigee-project-id) or an empty/unresolvable value is skipped with a warning (warn-and-skip), so no malformed relations are emitted.

Example fixture

See examples/components.yaml for ready-to-register sample Component entities exercising both annotation styles — useful for local smoke testing of the stitching processor.