@jumentix/sdk-rest-client

OpenAPI-driven REST client: call operationIds instead of hand-building URLs.

What it is

OpenAPI-driven REST client: call operationIds instead of hand-building URLs.

Why it exists

Hand-written fetch URLs drift from the OpenAPI contract. This client stays aligned with the spec.

When to use: Browser or Node consumers calling a Jumentix REST API described by OpenAPI.

When not to use: Realtime sockets (sdk-websocket-client), gRPC (sdk-grpc-client), or server persistence.

Responsibility in context

• Stack layer: SDK / HTTP adapter (consumer)
• Problem boundary it owns: RestApiClient request helper bound to OpenAPI operationIds.
• Used with: shared-contracts loads the spec; server side is HTTP adapters + REST guide.
• Typical composition: OpenAPI spec → shared-contracts → RestApiClient → your UI/service.
• Journeys: REST API guide (includes playground).
• Not responsible for: Authorizing users, defining domain rules, or hosting the API.

Prerequisites

• Bun 1.3.13+ (monorepo pin) or the Node runtime your service already uses
• Read Getting started first
• Basic TypeScript modules/import knowledge

Glossary

• Port — TypeScript contract the application depends on (no vendor types).
• Adapter — Concrete implementation that talks to a driver, broker, or protocol.
• Composition root — Process startup code that wires env → adapters → use-cases.

Numbered steps

1. Install

bun add @jumentix/sdk-rest-client

2. First success (under 30 min)

import { RestApiClient } from '@jumentix/sdk-rest-client';

const client = new RestApiClient('http://localhost:3000/api/1.0.0');
const response = await client.request({
  operationId: 'createUser',
  body: { username: 'john', password: 'StrongPass#123' }
});

### REST client with mock fetch

```ts
const client = api.createMockClient();

const created = await client.request({
  operationId: 'createTask',
  method: 'POST',
  path: '/tasks',
  body: {
    id: 'task-1',
    title: 'Generate REST SDK example',
    categoryId: 'work',
    completed: false
  }
});
const listed = await client.request({
  operationId: 'listTasks',
  method: 'GET',
  path: '/tasks?categoryId=work'
});

return {
  created,
  listed
};
```

const client = api.createMockClient();

const created = await client.request({
  operationId: 'createTask',
  method: 'POST',
  path: '/tasks',
  body: {
    id: 'task-1',
    title: 'Generate REST SDK example',
    categoryId: 'work',
    completed: false
  }
});
const listed = await client.request({
  operationId: 'listTasks',
  method: 'GET',
  path: '/tasks?categoryId=work'
});

return {
  created,
  listed
};

3. Core workflows

1. Construct with base URL

Point at your API prefix.

2. Call by operationId

Pass body/params matching the OpenAPI operation.

3. Handle envelope errors

Read structured error fields — do not assume thrown Error only.

4. Full practical surface (exports)

• RestApiClient

Use exports from application/adapters layers as described above — not from domain entities.

Common errors

Verify success: the first-success snippet runs (or typechecks against your service) and your use-case depends only on ports.

Junior checklist (“I can …”)

• I can call an operationId successfully against a local API or mock
• I know this package does not replace server adapters

Next step

Continue with sdk-websocket-client.