Skip to content

API Examples

Last Updated: 2025-11-23

Comprehensive code examples demonstrating real-world usage patterns for ocmonica's REST and gRPC APIs.

Available Examples

Authentication

Complete authentication workflows including:

  • User registration
  • Login and token management
  • Using access tokens in API requests
  • Token refresh flow
  • API key authentication
  • Logout
  • Password changes

Languages: curl, JavaScript/TypeScript, Python, Go

File Operations

File management examples including:

  • Upload files (with multipart form data)
  • Download files
  • List files with pagination
  • Get file metadata
  • Delete files
  • Move files between directories
  • Copy files
  • Preview text and code files
  • Stream media files (video/audio)

Languages: curl, JavaScript/TypeScript, Python, Go

Organization Management

Multi-tenant organization examples including:

  • Create organization
  • List organizations
  • Get organization details
  • Update organization settings
  • Delete organization
  • Add members to organization
  • List organization members
  • Update member roles
  • Remove members
  • Set primary organization

Languages: curl, JavaScript/TypeScript, Python, Go

RBAC (Role-Based Access Control)

Permission and role management examples including:

  • List roles
  • Create custom roles
  • Get role details
  • Update role permissions
  • Delete custom roles
  • Assign roles to users
  • Remove role assignments
  • Check user permissions
  • Permission enforcement patterns

Languages: curl, JavaScript/TypeScript, Python, Go

Watched Folders

Local filesystem monitoring examples including:

  • Add watched folder
  • List watched folders
  • Get watched folder details
  • Update watched folder settings
  • Remove watched folder
  • Trigger manual scan
  • Navigate folder contents

Languages: curl, JavaScript/TypeScript, Python, Go

Getting Started

All examples assume you have:

  1. A running ocmonica server (see Getting Started Guide)
  2. Authentication tokens (see Authentication Examples)
  3. Required permissions for the operations you want to perform

Quick Setup

# 1. Start the server
task dev

# 2. Login and get access token
ACCESS_TOKEN=$(curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  | jq -r '.access_token')

# 3. Use the token in requests
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://localhost:8080/api/v1/organizations

Example Structure

Each example file follows this structure:

  1. Operation Description - What the operation does
  2. REST API - HTTP endpoint and method
  3. Code Examples in multiple languages:
  4. curl - Direct HTTP requests
  5. JavaScript/TypeScript - Frontend and Node.js
  6. Python - Backend scripts and automation
  7. Go - Native Go client code
  8. Response Format - Expected JSON responses
  9. Error Handling - Common errors and solutions

Common Patterns

Error Handling

All APIs return consistent error responses:

{
  "error": "error message",
  "details": "additional context (optional)"
}

HTTP Status Codes: - 200 - Success - 201 - Created - 400 - Bad Request (invalid input) - 401 - Unauthorized (missing or invalid token) - 403 - Forbidden (insufficient permissions) - 404 - Not Found - 429 - Too Many Requests (rate limit exceeded) - 500 - Internal Server Error

Pagination

List endpoints support pagination:

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "http://localhost:8080/api/v1/files?limit=50&offset=100"

Response: 

{
  "files": [...],
  "total": 500,
  "limit": 50,
  "offset": 100
}

Rate Limiting

API responses include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699900000

Handle rate limits gracefully:

if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset');
  const waitTime = (parseInt(resetTime) * 1000) - Date.now();
  console.log(`Rate limited. Retry after ${waitTime}ms`);
}

Development Tips

Environment Variables

Store sensitive values in environment variables:

export OCMONICA_API_URL="http://localhost:8080"
export OCMONICA_ACCESS_TOKEN="your-access-token"
export OCMONICA_API_KEY="your-api-key"

Testing with curl

Use environment variables in curl:

curl -H "Authorization: Bearer ${OCMONICA_ACCESS_TOKEN}" \
  ${OCMONICA_API_URL}/api/v1/organizations

TypeScript Type Safety

Use generated types for gRPC clients:

import { FileService } from '@/gen/ocmonica/v1/file_service_connect';
import { createConnectTransport } from '@connectrpc/connect-web';
import { createPromiseClient } from '@connectrpc/connect';

const transport = createConnectTransport({
  baseUrl: 'http://localhost:8080',
});

const client = createPromiseClient(FileService, transport);

Additional Resources

Contributing Examples

Have a useful example to share? Contributions are welcome!

  1. Follow the existing example format
  2. Include all four languages (curl, JS/TS, Python, Go)
  3. Add error handling examples
  4. Test all code examples
  5. Submit a pull request

See CONTRIBUTING.md in the project root for guidelines.