Guide REST API Usage - osama1998H/Moca GitHub Wiki

REST API Usage

Auto-generated endpoints, filtering with operators, pagination, field selection, and API versioning.

Auto-Generated Endpoints

Every MetaType automatically gets CRUD endpoints:

Method Endpoint Action
GET /api/v1/document/{doctype} List documents
POST /api/v1/document/{doctype} Create document
GET /api/v1/document/{doctype}/{name} Get document
PUT /api/v1/document/{doctype}/{name} Update document
DELETE /api/v1/document/{doctype}/{name} Delete document

Site Header

All requests must include the site identifier:

X-Moca-Site: mysite

Interactive Docs

  • Open /api/docs in the browser for Swagger UI
  • Fetch /api/v1/openapi.json when you need a machine-readable OpenAPI document
  • Include X-Moca-Site when you want the generated spec to reflect the current site's DocTypes

Filtering

Use query parameters with operators:

# Simple equality
GET /api/v1/document/Task?filters=["status","=","Open"](/osama1998H/Moca/wiki/"status","=","Open")

# Multiple filters
GET /api/v1/document/Task?filters=["status","=","Open"],["priority","=","High"](/osama1998H/Moca/wiki/"status","=","Open"],["priority","=","High")

# Range
GET /api/v1/document/Task?filters=["amount",">","1000"](/osama1998H/Moca/wiki/"amount",">","1000")

# Like
GET /api/v1/document/Task?filters=["title","like","%urgent%"](/osama1998H/Moca/wiki/"title","like","%urgent%")

# In
GET /api/v1/document/Task?filters=["status","in",["Open","In Progress"](/osama1998H/Moca/wiki/"status","in",["Open","In-Progress")]

Pagination

GET /api/v1/document/Task?limit_start=0&limit_page_length=20

Field Selection

GET /api/v1/document/Task?fields=["name","title","status"]

Sorting

GET /api/v1/document/Task?order_by=creation desc

API Versioning

The API version is in the URL path (/api/v1/). Future versions will be added as /api/v2/, etc.

Rate Limiting

Redis-backed sliding window rate limiter. Default limits configurable in moca.yaml.

Related