OpenAPI Spec

Overview

This skill enables AI agents to use the Eclipse OpenAPI specification as the authoritative API contract when building applications on Eclipse. Use it alongside the Eclipse MCP server — the spec provides exact endpoint paths, schemas, and field constraints; the MCP server provides platform context and documentation.

OpenAPI spec: https://eclipse-java-sandbox.ukheshe.rocks/openapi

MCP server: https://developer.eftcorp.com/mcp

Using OpenAPI and MCP Together

Trigger: "build an app using Eclipse APIs", "generate an Eclipse API client", "what endpoints are available for X"

Load both resources at the start of any Eclipse development session:

1. Connect your AI tool to the MCP server — see MCP Setup
2. Fetch the OpenAPI spec from https://eclipse-java-sandbox.ukheshe.rocks/openapi
3. Load any relevant Skills for the workflows your application needs

With all three active, the AI has the platform vocabulary (MCP), the exact API contract (OpenAPI spec), and proven call sequences for common operations (Skills).

Eclipse API Conventions

All tenant-scoped endpoints follow the pattern:

{method} https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/...

Every authenticated request requires:

Authorization: Bearer {jwt}

See the Authentication skill for the login flow.

Eclipse errors are returned as a JSON array regardless of operation:

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "Insufficient funds",
    "code": "WAL009",
    "traceId": "3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d",
    "spanId": "1a2b3c4d5e6f7a8b"
  }
]

Always surface traceId to the user when present.

Navigating the Spec

Filter paths by keyword to locate endpoints for a capability:

For each endpoint, resolve $ref values in requestBody and responses to components/schemas to get exact field names, types, and required constraints. Never guess field names — the spec is authoritative.

Common Patterns

Generate an API client

1. Fetch https://eclipse-java-sandbox.ukheshe.rocks/openapi
2. Extract paths and schemas for the target capability
3. Generate typed client methods — one per operation — with request/response types from components/schemas
4. Add JWT authentication from the Authentication skill

Validate a request before sending

1. Resolve the schema for the target endpoint's request body
2. Confirm all fields in required are present
3. Confirm value types match schema declarations
4. Generate externalUniqueId as a UUID on any mutating operation — duplicates are rejected with 409 Conflict

Build a new application

1. Use the MCP server for platform context and to understand which capabilities apply to the use case
2. Fetch the OpenAPI spec to access the full API surface and exact schemas
3. Load the relevant Skills for the application's core workflows
4. Generate code using field names from the spec and call sequences from the Skills

Notes

• The OpenAPI spec reflects the sandbox environment. Test all generated code against the sandbox before promoting to production — wallet type constraints, tenant configuration, and permission requirements are enforced at runtime and are not fully captured in the schema.
• When the MCP server and the OpenAPI spec disagree on a field name or path, the OpenAPI spec is authoritative.
• Apply limit and offset pagination on all list endpoints. Default to limit=20.
• Mask sensitive data in output — never log or display full identity numbers, card numbers, or JWTs.