Skip to content
OstrichDB

API Overview

API Overview

Section titled “API Overview”

OstrichDB provides a comprehensive RESTful API that allows you to interact with the hierarchical database structure. All endpoints follow REST conventions and return JSON responses.

Base URL

Section titled “Base URL”

The API is available at:

http://localhost:8042/api/v1/

Authentication

Section titled “Authentication”

Most API endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer your-jwt-token-here

Response Format

Section titled “Response Format”

All API responses follow a consistent JSON format:

Success Response

Section titled “Success Response”
{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully"
}

Error Response

Section titled “Error Response”
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details"
  }
}

HTTP Status Codes

Section titled “HTTP Status Codes”

The API uses standard HTTP status codes:

  • 200 OK: Successful GET, PUT requests
  • 201 Created: Successful POST requests
  • 204 No Content: Successful DELETE requests
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource doesn’t exist
  • 409 Conflict: Resource already exists
  • 500 Internal Server Error: Server error

Endpoint Categories

Section titled “Endpoint Categories”

Projects

Section titled “Projects”

Manage top-level project containers:

  • List projects
  • Create new projects
  • Rename projects
  • Delete projects

Collections

Section titled “Collections”

Manage data collections within projects:

  • List collections
  • Create collections
  • Get collection information
  • Rename collections
  • Delete collections

Clusters

Section titled “Clusters”

Manage record clusters within collections:

  • List clusters
  • Create clusters
  • Get cluster data
  • Rename clusters
  • Delete clusters

Records

Section titled “Records”

Manage individual data records:

  • List records with filtering
  • Create records with types
  • Get specific records
  • Update records
  • Delete records

Common Parameters

Section titled “Common Parameters”

Path Parameters

Section titled “Path Parameters”

All endpoints use hierarchical path parameters:

  • {project}: Project name
  • {collection}: Collection name
  • {cluster}: Cluster name
  • {record}: Record name or ID

Query Parameters

Section titled “Query Parameters”

Filtering

Section titled “Filtering”
  • type: Filter by data type (STRING, INTEGER, etc.)
  • search: Search in record names (partial match)
  • value: Match exact values
  • valueContains: Partial value matching

Sorting

Section titled “Sorting”
  • sortBy: Sort field (name, value, type, id)
  • sortOrder: Sort direction (asc, desc)

Pagination

Section titled “Pagination”
  • limit: Maximum number of results
  • offset: Number of results to skip

Rate Limiting

Section titled “Rate Limiting”

The API implements rate limiting to ensure fair usage:

  • Default limit: 1000 requests per hour per user
  • Burst limit: 100 requests per minute
  • Headers: Rate limit information included in response headers

CORS Support

Section titled “CORS Support”

Cross-Origin Resource Sharing (CORS) is enabled for web applications:

  • Allowed origins: Configurable in server settings
  • Allowed methods: GET, POST, PUT, DELETE, OPTIONS
  • Allowed headers: Content-Type, Authorization

Health Check

Section titled “Health Check”

Check server status:

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Error Handling

Section titled “Error Handling”

Common Error Codes

Section titled “Common Error Codes”
  • INVALID_REQUEST: Malformed request parameters
  • AUTHENTICATION_FAILED: Invalid or missing JWT token
  • AUTHORIZATION_FAILED: Insufficient permissions
  • RESOURCE_NOT_FOUND: Requested resource doesn’t exist
  • RESOURCE_EXISTS: Attempting to create existing resource
  • VALIDATION_ERROR: Data validation failed
  • SERVER_ERROR: Internal server error

Error Response Example

Section titled “Error Response Example”
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid data type specified",
    "details": "Supported types: STRING, INTEGER, FLOAT, BOOLEAN, DATE, TIME, DATETIME, UUID, NULL, CREDENTIAL, and array variants"
  }
}

Next Steps

Section titled “Next Steps”

Explore specific API endpoints: