objectstack-api

API Design — ObjectStack API Protocol

Expert instructions for designing REST APIs, service contracts, and integration protocols using the ObjectStack specification. This skill covers endpoint definitions, API discovery, authentication, dispatcher configuration, and inter-service communication patterns.

---

When to Use This Skill

• You are defining custom REST API endpoints beyond auto-generated CRUD.
• You need to configure API authentication and authorization.
• You are setting up service discovery and health checks.
• You are designing inter-service communication (service-to-service calls).
• You need to understand the dispatcher routing system.
• You are integrating external APIs via datasource connectors.

---

Auto-Generated vs Custom APIs

Auto-Generated APIs

Every ObjectStack object with apiEnabled: true (the default) automatically gets a full REST API:

GET    /api/v1/data/{object}          # List records (with filter, sort, pagination)
GET    /api/v1/data/{object}/:id      # Get single record
POST   /api/v1/data/{object}          # Create record
PATCH  /api/v1/data/{object}/:id      # Update record
DELETE /api/v1/data/{object}/:id      # Delete record (hard delete)
POST   /api/v1/data/{object}/query    # Complex queries + aggregation (QueryAST in body)
POST   /api/v1/data/{object}/batch    # Per-object batch operations
POST   /api/v1/batch                  # Cross-object atomic batch

Data CRUD lives under the /data prefix. There is no /bulk route and no GET .../aggregate route — batch writes go through the batch endpoints, and aggregation goes through POST /api/v1/data/{object}/query with groupBy/aggregations in the body.

Key rule: If your object defines apiMethods, only those operations (and what derives from them) are exposed. For example, apiMethods: ['get', 'list'] creates a read-only API. The authorable values are the SIX PRIMITIVES (get/list/create/update/delete/bulk); everything else (export, search, upsert, …) is DERIVED from them by the server — ['list'] grants aggregate/search/export for free, ['create','update'] grants upsert/import. An empty array [] means deny-all (fully closed).