From 6a310197748987e710eef32726d24accd109909f Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 14 May 2026 13:43:21 -0600 Subject: [PATCH] docs: document rest: true config.yaml prerequisite for automatic APIs Agents were failing to debug missing REST endpoints because the docs didn't mention that `rest: true` must be set in `config.yaml` for `@export`ed tables to respond to HTTP requests. Added the requirement as the first step in automatic-apis.md and as a callout wherever `@table @export` is introduced. Co-Authored-By: Claude Sonnet 4.6 --- harper-best-practices/AGENTS.md | 2 +- .../rules/adding-tables-with-schemas.md | 2 +- harper-best-practices/rules/automatic-apis.md | 15 ++++++++++----- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/harper-best-practices/AGENTS.md b/harper-best-practices/AGENTS.md index 3d87705..51638ac 100644 --- a/harper-best-practices/AGENTS.md +++ b/harper-best-practices/AGENTS.md @@ -50,7 +50,7 @@ Use this skill when you need to define new data structures or modify existing on 1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file. 2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`. 3. **Define Relationships**: Link tables together using the `@relationship` directive. -4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. +4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. 5. **Consider Table Extensions**: If you are going to extend the table in your resources, then do not `@export` the table from the schema. #### Example diff --git a/harper-best-practices/rules/adding-tables-with-schemas.md b/harper-best-practices/rules/adding-tables-with-schemas.md index 3849850..fe7e83d 100644 --- a/harper-best-practices/rules/adding-tables-with-schemas.md +++ b/harper-best-practices/rules/adding-tables-with-schemas.md @@ -16,7 +16,7 @@ Use this skill when you need to define new data structures or modify existing on 1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file. 2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`. 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill. -4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill. +4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill. - `GET /{TableName}`: Describes the schema itself. - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details. - `GET /{TableName}/{id}`: Retrieves a single record by its ID. diff --git a/harper-best-practices/rules/automatic-apis.md b/harper-best-practices/rules/automatic-apis.md index a737877..dba926c 100644 --- a/harper-best-practices/rules/automatic-apis.md +++ b/harper-best-practices/rules/automatic-apis.md @@ -13,11 +13,16 @@ Use this skill when you want to interact with Harper tables via REST or WebSocke ## How It Works -1. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table. -2. **Access REST Endpoints**: Use the standard endpoints for your table (Note: Paths are case-sensitive). -3. **Use Automatic WebSockets**: Connect to `wss://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. (Use `ws://` for local development without SSL). For more complex needs, see [Real-time Apps](real-time-apps.md). -4. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details. -5. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md). +1. **Enable REST in `config.yaml`**: REST endpoints are **not active by default**. You must explicitly enable them: + ```yaml + rest: true + ``` + Without this, `@export`ed tables will not respond to HTTP requests. +2. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table. +3. **Access REST Endpoints**: Use the standard endpoints for your table (Note: Paths are case-sensitive). +4. **Use Automatic WebSockets**: Connect to `wss://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. (Use `ws://` for local development without SSL). For more complex needs, see [Real-time Apps](real-time-apps.md). +5. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details. +6. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md). ## Examples