Skip to content

Define the resource service's API in one contract and generate code from it #9485

Open

Description

@bobbai00

Task Summary

No file defines Texera's API today: each of its 235 endpoints is declared by hand in up to three places, the Scala resource class, the Angular service and the agent service's client (#5918). This task defines the resource service's API once, before the service is built (#9489), and generates the code on every side from it.

  1. One contract. A TypeSpec contract in api/ gives every kind the same operations, as listed in Proposal: Unify Backend Resource Management On Texera #9395: create, list, read, update and delete, versions, and access. Each kind adds its own operations, such as uploading a file to a dataset or terminating a computing unit, and every operation states the permission it needs.
  2. Generated code. The contract compiles to OpenAPI. OpenAPI Generator makes the Scala server interfaces from it, and @hey-api/openapi-ts makes the TypeScript client for the frontend and the agent service. Generated code is committed, and CI fails when it is out of date.
  3. A version prefix. New routes live under /api/v1/, as parshimers suggested in Proposal: Unify Backend Resource Management On Texera #9395, which also keeps them apart from today's routes while both exist.
  4. Ready for MCP. Every operation has a stable id, a one-line summary and described parameters. A tag marks the operations that become tools, and a tool call goes through the same route with the user's token. Long work, such as an execution, can be started, read and stopped over HTTP. The tool definitions are generated, and Serve the agent's workflow tools from a Texera MCP server #9457 serves them.

Discussion points

  1. Scala server code: OpenAPI Generator's jaxrs-spec interfaces with Java model classes, or our own templates that emit Scala case classes. A pilot on config-service decides.
  2. Where the version goes: in the path, or in a header, which parshimers also offered.

Done when the contract covers every kind's standard operations, and CI regenerates the server interfaces and the client from it.

Task Type

  • Refactor / Cleanup
  • DevOps / Deployment / CI
  • Testing / QA
  • Documentation
  • Performance
  • Other

Activity

  1. added theissue type on Nov 16, 2026
  2. changed the title [-]Describe the backend API in one contract and generate code from it[/-] [+]Define the resource service's API in one contract and generate code from it[/+] on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions