REST API Documentation

Last Updated: 2025-11-23

This document describes the REST API implementation in ocmonica, including available endpoints, authentication patterns, and usage examples.

---

Table of Contents

• Overview
• Base URL
• Authentication
• Available Endpoints
• Error Handling
• Rate Limiting

---

Overview

Ocmonica's REST API is built with Echo v4.13.4 and provides traditional HTTP/JSON endpoints for web browsers, curl, and standard HTTP clients.

Key Features: - ✅ Universal HTTP client compatibility - ✅ JSON request/response format - ✅ Comprehensive authentication endpoints - ✅ Health checks and metrics - ✅ CORS support - ✅ Rate limiting - ✅ OpenTelemetry tracing

---

Base URL

http://localhost:8080/api/v1

All REST endpoints are prefixed with /api/v1/.

---

Authentication

Authentication Flow

Authentication is REST-only. Clients must: 1. Login via REST API (POST /api/v1/auth/login) 2. Receive JWT access token + refresh token 3. Use access token for both REST and gRPC requests

REST Authentication (internal/api/rest/middleware/auth.go):

// JWT middleware validates token and adds claims to context
func JWTMiddleware(tokenService *service.TokenService) echo.MiddlewareFunc {
    return echojwt.WithConfig(echojwt.Config{
        SigningMethod: "RS256",
        SigningKey:    tokenService.GetPublicKey(),
        // ... extracts user_id, organization_id, role
    })
}

JWT Token Flow

1. User logs in → receive access + refresh tokens
2. Access token used for API requests (15min TTL)
3. When access token expires, use refresh token to get new pair
4. Refresh tokens are single-use (automatic rotation)
5. All tokens revoked on password change

Using Tokens

Include the access token in the Authorization header:

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:8080/api/v1/files

---

Available Endpoints

Authentication Endpoints

Endpoint	Method	Description	Auth Required
/auth/register	POST	Register new user	No
/auth/login	POST	Login and receive tokens	No
/auth/logout	POST	Logout and revoke tokens	Yes
/auth/refresh	POST	Refresh access token	Refresh token
/auth/profile	GET	Get current user profile	Yes
/auth/profile	PUT	Update user profile	Yes
/auth/password	PUT	Change password	Yes

Implementation: internal/api/rest/handlers/auth.go

File Operations

Endpoint	Method	Description	Auth Required
/files	POST	Upload file	Yes
/files	GET	List files	Yes
/files/:id	GET	Get file metadata	Yes
/files/:id/download	GET	Download file	Yes
/files/:id	PUT	Update file metadata	Yes
/files/:id	DELETE	Delete file	Yes
/files/:id/move	POST	Move file	Yes
/files/:id/copy	POST	Copy file	Yes

Implementation: internal/api/rest/handlers/file.go

Directory Operations

Endpoint	Method	Description	Auth Required
/directories	POST	Create directory	Yes
/directories	GET	List directories	Yes
/directories/:id	GET	Get directory	Yes
/directories/:id	DELETE	Delete directory	Yes
/directories/:id/move	POST	Move directory	Yes

Implementation: internal/api/rest/handlers/directory.go

Search

Endpoint	Method	Description	Auth Required
/search	GET	Search files and directories	Yes

Implementation: internal/api/rest/handlers/search.go

Note: REST search returns a single response. For server-streaming search, use the gRPC API's SearchStream method.

Organization Management

Endpoint	Method	Description	Auth Required
/organizations	POST	Create organization	Yes
/organizations	GET	List organizations	Yes
/organizations/:id	GET	Get organization	Yes
/organizations/:id	PUT	Update organization	Yes
/organizations/:id	DELETE	Delete organization	Yes

Implementation: internal/api/rest/handlers/organization_handler.go

Role Management (RBAC)

Endpoint	Method	Description	Auth Required
/roles	POST	Create role	Yes (admin)
/roles	GET	List roles	Yes
/roles/:id	GET	Get role	Yes
/roles/:id	PUT	Update role	Yes (admin)
/roles/:id	DELETE	Delete role	Yes (admin)
/roles/:id/assign	POST	Assign role to user	Yes (admin)
/roles/:id/unassign	POST	Unassign role from user	Yes (admin)

Implementation: internal/api/rest/handlers/role_handler.go

Permission Format: resource:action (e.g., file:read, file:write, org:admin)

API Key Management

Endpoint	Method	Description	Auth Required
/api-keys	POST	Create API key	Yes
/api-keys	GET	List API keys	Yes
/api-keys/:id	DELETE	Revoke API key	Yes

Implementation: internal/api/rest/handlers/api_key.go

Group Management

Endpoint	Method	Description	Auth Required
/groups	POST	Create group	Yes
/groups	GET	List groups	Yes
/groups/:id	GET	Get group	Yes
/groups/:id	PUT	Update group	Yes
/groups/:id	DELETE	Delete group	Yes
/groups/:id/members	POST	Add member	Yes
/groups/:id/members/:userId	DELETE	Remove member	Yes
/groups/:id/members	GET	List members	Yes

Implementation: internal/api/rest/handlers/group_handler.go

Watched Folders

Endpoint	Method	Description	Auth Required
/watched-folders	POST	Create watched folder	Yes
/watched-folders	GET	List watched folders	Yes
/watched-folders/:id	GET	Get watched folder	Yes
/watched-folders/:id	PUT	Update watched folder	Yes
/watched-folders/:id	DELETE	Delete watched folder	Yes
/watched-folders/:id/scan	POST	Trigger scan	Yes
/watched-folders/:id/files	GET	Get indexed files	Yes

Implementation: internal/api/rest/handlers/watched_folder_handler.go

Health & Monitoring

Endpoint	Method	Description	Auth Required
/health	GET	Health check	No
/metrics	GET	Prometheus metrics	No

Implementation: internal/api/rest/handlers/health_handler.go

---

Error Handling

The REST API returns standard HTTP status codes:

Status Code	Meaning
200	Success
201	Created
400	Bad Request (validation error)
401	Unauthorized (invalid/missing token)
403	Forbidden (permission denied)
404	Not Found
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Error Response Format:

{
  "message": "error description",
  "error": "detailed error message"
}

---

Rate Limiting

Rate limits are enforced per IP address:

Endpoint Category	Rate Limit
Global	100 requests/minute
Login/Register	5 requests/minute
Other auth endpoints	10 requests/minute

Rate Limit Headers: - X-RateLimit-Limit: Maximum requests allowed - X-RateLimit-Remaining: Remaining requests - X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Note: Current implementation is in-memory (per instance). For distributed deployments, consider using Redis.

---

Example Usage

Register a New User

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "securepassword123",
    "organization_name": "My Company"
  }'

Login

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "securepassword123"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 900
}

Upload a File

curl -X POST http://localhost:8080/api/v1/files \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@document.pdf" \
  -F "directory_id=<directory_id>"

List Files

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:8080/api/v1/files

Search

curl -H "Authorization: Bearer <access_token>" \
  "http://localhost:8080/api/v1/search?q=report&type=file"

---

See Also

• gRPC API Documentation
• Swagger/OpenAPI Documentation
• Architecture Overview
• Authentication Guide
• Getting Started Guide