Add JAX-RS endpoint support to the Product Knowledge Graph

[pritam0802]

Hi team,
I would like to contribute JAX-RS endpoint detection to Spine.
Spine already understands Java classes and methods. However, I could not find support for identifying JAX-RS REST endpoints in the Product Knowledge Graph.
For example:

@Path("/orders")
public class OrderResource {

    @GET
    @Path("/{id}")
    public Order getOrder(@PathParam("id") String id) {
        return orderService.find(id);
    }
}

Spine could identify this as:

Endpoint: GET /orders/{id}
Handler: OrderResource.getOrder()
Source: OrderResource.java

Initial scope
I propose starting with:

• Detect @path on classes and methods.
• Detect @get, @post, @put, @delete and @patch.
• Combine the class path and method path.
• Create an Endpoint node in the Product Knowledge Graph.
• Add an EXPOSES edge from the endpoint to its Java method.
• Keep the exact file and line information.
• Add tests to make sure the result is deterministic.

Why this can help
This would help Spine:

• Understand Java REST services better.
• Find the correct API when planning a change.
• Generate code using existing endpoints.
• Show the impact of changing an endpoint.
• Review API changes more accurately.
• Generate better tests for REST APIs.

This would be useful for JAX-RS, Jakarta REST and Helidon applications.
Out of scope for this change
To keep the contribution small, I would not include:

• Spring MVC
• Helidon SE programmatic routing
• JPA entity detection
• CDI dependency injection
• OpenAPI parsing

These can be discussed as separate improvements later.
Questions
Before I start, I would like guidance on:
Does this fit the current direction of the Spine Product Knowledge Graph?
Should JAX-RS endpoints use the existing Endpoint and EXPOSES graph types?
Are there existing extractor patterns that I should follow?
Is there any work already in progress for Java framework support?

[ssmith-synaptixs]

Yes — this fits, and we'd welcome it. Use the existing Endpoint and EXPOSES graph types exactly as you propose. The C# extractor already does the same thing for ASP.NET routes, so there is a working pattern to copy, and nothing conflicts with work in progress. The timing is also good: the knowledge base now includes an API surface page that is generated automatically for any repo whose graph contains endpoints — your contribution switches that on for Java REST services with no extra work.

Answers to your questions

1. Does this fit the current direction of the Product Knowledge Graph?

Yes. Endpoints and EXPOSES were designed to be language-neutral; C# is simply the first language that emits them. Framework-aware edges are an established capability, and Java is the natural next language. Your plan also puts the logic in the right place — the extractor, not the renderers — which matches how the graph is meant to grow.

2. Should JAX-RS endpoints use the existing Endpoint and EXPOSES types?

Yes, with this exact shape so Java matches C#:

Edge direction is endpoint → handler.
Endpoint id: java:endpoint:GET /orders/{id}; node name: GET /orders/{id}.
Provenance: the handler method's file and line.
Keep {id} path templates verbatim.
Two handlers with the same verb and path merge into one endpoint node — known, accepted behaviour (C# is the same).

3. Are there existing extractor patterns to follow?
   Yes — the C# extractor's endpoint pass is your direct template: read the class-level route, read each method's verb and route annotations, join them, emit the node and edge. A few Java-specific notes:

Stay per-file: class and method annotations are in the same file, so no whole-repo pass is needed.
Match annotation names by their last segment, so @get and @jakarta.ws.rs.GET both work — and javax vs jakarta becomes a non-issue.
In tests, assert the exact expected endpoint and edge, including that the handler resolves to a real, grounded method node — not just that something was emitted. Also assert determinism by extracting the fixture twice and comparing.

4. Is there any Java framework work already in progress?
   No — the field is clear. Two useful facts: Java call-graph edges now exist (so "impact of changing an endpoint" will work through your EXPOSES edges), and the "busiest controllers" statistic currently only counts classes named *Controller, so *Resource classes won't appear there. That's fine for this change; broadening it can be a separate follow-up.

Suggestions from our side

1. Add @Head and @options — same mechanism, completes the standard verbs.
2. Cover both asymmetric cases: class @path with a verb-only method, and a method @path on a class without one. Add a fixture for each.
3. Skip sub-resource locators (a method with @path but no verb annotation) rather than guessing a verb. Resolving them needs cross-class analysis; skipping-not-guessing is the house style. Just note the skip in the docstring.
4. Say what's omitted: one docstring line noting @Produces/@consumes are not captured.
5. Add @ApplicationPath to your out-of-scope list — it lives in a different file, so it can't be handled per-file. Everything else you excluded (Spring MVC, Helidon SE, JPA, CDI, OpenAPI) we agree belongs in separate contributions.

Practicalities
Branch off, develop, run the full quality gate from the contributing guide (type checks cover tests too, not just source), and keep the Java tests skipping cleanly when the optional Java extra isn't installed. With the C# pattern to copy, this is roughly a day or two of work. We're happy to review a draft early — even just the fixture and the expected edge set — before you polish.`

[ssmith-synaptixs]

@pritam0802 Please follow the contributing guide and let us know if you have more questions.