Basic REST API

A minimal example demonstrating basic CRUD operations with Soxom.

OpenAPI Specification

openapi.yaml

openapi: 3.1.0
info:
  title: Tasks API
  version: 1.0.0

servers:
  - url: https://api.tasks.example.com/v1

security:
  - bearerAuth: []

paths:
  /tasks:
    get:
      operationId: listTasks
      summary: List all tasks
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, completed]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: List of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Task"
                  has_more:
                    type: boolean

    post:
      operationId: createTask
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskCreate"
      responses:
        "201":
          description: Task created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"

  /tasks/{task_id}:
    parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string

    get:
      operationId: getTask
      summary: Get a task
      responses:
        "200":
          description: Task details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"

    put:
      operationId: updateTask
      summary: Update a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskUpdate"
      responses:
        "200":
          description: Task updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"

    delete:
      operationId: deleteTask
      summary: Delete a task
      responses:
        "204":
          description: Task deleted

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    Task:
      type: object
      required:
        - id
        - title
        - status
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [pending, completed]
        created_at:
          type: string
          format: date-time

    TaskCreate:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string

    TaskUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [pending, completed]

Soxom Configuration

soxom.yaml

version: "1.0"

sdk:
  name: tasks-sdk
  version: 1.0.0
  description: SDK for Tasks API

spec:
  path: ./openapi.yaml

targets:
  - typescript
  - python

resources:
  tasks:
    models:
      - Task
      - TaskCreate
      - TaskUpdate
    methods:
      list: get /tasks
      create: post /tasks
      get: get /tasks/{task_id}
      update: put /tasks/{task_id}
      delete: delete /tasks/{task_id}

pagination:
  default_type: cursor
  schemes:
    cursor:
      has_more:
        response_property: has_more

authentication:
  default: bearer
  env_vars:
    bearer:
      token: TASKS_API_TOKEN

Generate SDK

Commit and push openapi.yaml and soxom.yaml to your Config Repository. Soxom builds the SDK automatically — watch progress in the Builds view of the dashboard.

Generated SDK Usage

TypeScript

import { TasksClient } from 'tasks-sdk';

const client = new TasksClient({
  token: process.env.TASKS_API_TOKEN
});

// List all tasks
const tasks = await client.tasks.list();
console.log(tasks.data);

// List with filter
const pendingTasks = await client.tasks.list({
  status: 'pending'
});

// Auto-iterate through all pages
for await (const task of client.tasks.list()) {
  console.log(task.title);
}

// Create a task
const newTask = await client.tasks.create({
  title: "Write documentation",
  description: "Create SDK documentation"
});
console.log(`Created: ${newTask.id}`);

// Get a task
const task = await client.tasks.get("task-123");
console.log(task.title);

// Update a task
const updated = await client.tasks.update("task-123", {
  status: "completed"
});

// Delete a task
await client.tasks.delete("task-123");

Python

from tasks_sdk import TasksClient

client = TasksClient(
    token=os.environ["TASKS_API_TOKEN"]
)

# List all tasks
tasks = client.tasks.list()
print(tasks.data)

# List with filter
pending_tasks = client.tasks.list(status="pending")

# Auto-iterate through all pages
for task in client.tasks.list():
    print(task.title)

# Create a task
new_task = client.tasks.create(
    title="Write documentation",
    description="Create SDK documentation"
)
print(f"Created: {new_task.id}")

# Get a task
task = client.tasks.get("task-123")
print(task.title)

# Update a task
updated = client.tasks.update("task-123", status="completed")

# Delete a task
client.tasks.delete("task-123")

What This Example Demonstrates

• Basic CRUD operations (Create, Read, Update, Delete)
• List endpoint with filtering
• Simple cursor pagination
• Bearer token authentication
• Minimal configuration