# REST-API Configuration (cf.cplace.rest.config)

## Overview

The REST-API Configuration app provides a no-code/low-code framework for exposing cplace entities as RESTful HTTP resources. Configuration is modeled entirely as cplace pages — Endpoint, Schema, Attribute, Conversion, and Resource entities form a hierarchical structure that maps cplace types and attributes to REST API paths and fields.

**There are no UI widgets in this app.** It provides configuration types only; the REST endpoints are served by the companion dispatch plugin.

## Dependencies

- `cf.cplace.platform` (cplace Basis) — always pre-installed

No additional apps are auto-installed with this app. The dispatch runtime (`cf.cplace.rest.dispatch`) is a separate plugin that must also be installed for endpoints to be reachable.

## Types Provided

### cf.cplace.rest.endpoint

The top-level configuration entity. Each Endpoint page represents a distinct REST API base path.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Path Segment | `cf.cplace.rest.pathSegment` | String | Yes | No | URL path segment, e.g. "v1" |
| Enabled | `cf.cplace.rest.enabled` | Boolean | No | No | Whether the endpoint is active (default: false) |
| Production Mode | `cf.cplace.rest.productionMode` | Boolean | No | No | Restricts editing when enabled (default: false) |
| Allowed Principals | `cf.cplace.rest.allowedPrincipals` | Multi Principal Ref | No | Yes | Access control (default: allusers) |
| OAS Enabled | `cf.cplace.rest.oasEnabled` | Boolean | No | No | Enable OpenAPI spec generation (default: false) |
| OAS Title | `cf.cplace.rest.oasTitle` | String | No | No | OpenAPI spec title |
| OAS Description | `cf.cplace.rest.oasDescription` | String | No | No | OpenAPI spec description |
| OAS Contact Name | `cf.cplace.rest.oasContactName` | String | No | No | OpenAPI contact name |
| OAS Contact URL | `cf.cplace.rest.oasContactUrl` | String | No | No | OpenAPI contact URL |
| OAS Contact Email | `cf.cplace.rest.oasContactEmail` | String | No | No | OpenAPI contact email |
| OAS Document Version | `cf.cplace.rest.oasDocumentVersion` | String | No | No | OpenAPI spec version string |

**Hierarchy**: Endpoint pages are the root of the REST configuration hierarchy. Schema and Resource pages are created as children.

### cf.cplace.rest.schema

Defines what kind of cplace entity is exposed through the REST API.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Entity Kind | `cf.cplace.rest.entityKind` | Dynamic String Enum | Yes | No | The type of cplace entity (see EntityKind values below) |
| Custom Type | `cf.cplace.rest.customType` | Dynamic String Enum | No | No | Pin to a specific cplace type's internal name |
| Endpoint | `cf.cplace.rest.endpoint` | Page Ref (Endpoint) | Yes | No | Parent endpoint (hierarchy) |

**EntityKind enum values:**
| Display | Internal Value | Notes |
|---------|----------------|-------|
| Workspace | `pageSpace` | Workspace entities |
| Page | `page` | Standard cplace pages (most common) |
| Document | `document` | File/document entities |
| Group | `group` | User groups |
| Script | `script` | Script entities |
| Comment | `comment` | Comment entities |
| Batch Job | `persistentJob` | Background jobs |
| Sent Email | `sentEmail` | Email log entries |
| System Group | `systemGroup` | System groups |
| Person | `person` | User/person entities |

**Hierarchy**: Schema pages are children of an Endpoint page. Attribute pages are children of Schema pages.

### cf.cplace.rest.attribute

Maps an internal cplace attribute to an external REST API field name.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Schema | `cf.cplace.rest.schema` | Page Ref (Schema) | Yes | No | Parent schema (hierarchy) |
| Internal Attribute | `cf.cplace.rest.internalAttribute` | Dynamic String Enum | Yes | No | Internal attribute name (e.g. `cf.cplace.title`) |
| External Name | `cf.cplace.rest.externalName` | String | Yes | No | Field name in the REST API response (camelCase) |
| Is Queryable | `cf.cplace.rest.queryable` | Boolean | No | No | Allow filtering by this field (default: false) |
| Is Key | `cf.cplace.rest.isKey` | Boolean | No | No | Use as entity identifier (default: false) |
| Conversion Parameters | `cf.cplace.rest.conversionParameters` | Page Ref | No | No | Link to a conversion type page |

**Hierarchy**: Attribute pages are children of a Schema page. Conversion pages are linked via `cf.cplace.rest.conversionParameters`.

### cf.cplace.rest.resource

Defines a specific REST resource path with allowed HTTP methods.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Endpoint | `cf.cplace.rest.endpoint` | Page Ref (Endpoint) | Yes | No | Parent endpoint (hierarchy) |
| Path Segment | `cf.cplace.rest.pathSegment` | String | Yes | No | URL path segment, e.g. "projects" |
| Method | `cf.cplace.rest.method` | Multi Enum | Yes | Yes | HTTP methods: GET_SINGLE, GET_MULTI, POST, PATCH, DELETE |
| Search | `cf.cplace.rest.search` | Search constraint | Yes | No | Scopes which entities this resource can access |
| Schema | `cf.cplace.rest.schema` | Page Ref (Schema) | No | No | Associated schema for this resource |
| Enabled | `cf.cplace.rest.enabled` | Boolean | No | No | Whether this resource is active (default: true) |
| File Method | `cf.cplace.rest.fileMethod` | Multi Enum | No | Yes | File HTTP methods: GET_FILE, POST_FILE, PATCH_FILE, DELETE_FILE |

**RequestMethod enum values**: `GET_SINGLE`, `GET_MULTI`, `POST`, `PATCH`, `DELETE`

**Hierarchy**: Resource pages are children of an Endpoint page.

### cf.cplace.rest.referenceConversion

Controls how reference attributes are serialized in the REST response.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Reference Schemas | `cf.cplace.rest.referenceSchemas` | Multi Page Ref (Schema) | No | Yes | Schemas defining the referenced entity structure |
| Reference Strategy | `cf.cplace.rest.referenceStrategy` | Enum | No | No | ID, UID, NAME, or SCHEMA |

**Use when**: The attribute is a page reference or multi-reference. Default strategy: `UID`.

### cf.cplace.rest.enumConversion

Controls how enum attributes are serialized.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Strategy | `cf.cplace.rest.strategy` | Enum | No | No | NAME or ALL_TRANSLATIONS |

**Use when**: The attribute is an enum or dynamic enum. Default: `NAME`.

### cf.cplace.rest.localizedStringConversion

Controls how localized string attributes are serialized.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Strategy | `cf.cplace.rest.strategy` | String | No | No | Language code (e.g. "en") or "ALL_TRANSLATIONS" |

**Use when**: The attribute is a localized string (multi-language text). Default: `ALL_TRANSLATIONS`.

### cf.cplace.rest.changesetConversion

Controls how changeset/history attributes are serialized.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Max Changes Size | `cf.cplace.rest.maxChangesSize` | Number | No | No | Maximum number of changes to include (default: 10) |

**Use when**: The attribute tracks change history.

### cf.cplace.rest.lowcodeConversion

Allows custom JavaScript scripts to transform attribute values.

| Attribute | Internal Name | Type | Required | Multiple | Description |
|-----------|--------------|------|----------|----------|-------------|
| Export Script | `cf.cplace.rest.exportScript` | Script | No | No | Script to transform value for GET responses |
| Import Script | `cf.cplace.rest.importScript` | Script | No | No | Script to transform value for POST/PATCH requests |

**Use when**: Standard conversions are insufficient and custom transformation logic is needed.

## Entity Hierarchy and Creation Order

The hierarchy determines page parent-child relationships and creation order:

```
Endpoint (cf.cplace.rest.endpoint)          ← create first
  ├── Schema (cf.cplace.rest.schema)         ← create second (parent: Endpoint)
  │     └── Attribute (cf.cplace.rest.attribute)  ← create third (parent: Schema)
  │           └── Conversion (optional)      ← create fourth (linked via conversionParameters)
  └── Resource (cf.cplace.rest.resource)     ← create last (parent: Endpoint, links Schema)
```

**Enable the Endpoint last** after all children are configured: update `cf.cplace.rest.enabled` = true.

## URL Structure

The dispatch plugin routes requests as:
```
/rest/{endpoint-pathSegment}/{resource-pathSegment}          — GET multi, POST
/rest/{endpoint-pathSegment}/{resource-pathSegment}/{id}     — GET single, PATCH, DELETE
/rest/{endpoint-pathSegment}/{resource-pathSegment}/bulk     — POST bulk, PATCH bulk
```

## Widgets Provided

None. This app provides configuration types only.

## Usage Notes

### When to Select This App

Select `cf.cplace.rest.config` when requirements mention:
- "REST API", "REST endpoints", "external API access"
- "integration", "third-party access", "API consumers"
- "programmatic access", "API clients"
- "expose data as API", "CRUD via API"

### Common Patterns

1. **Standard CRUD resource**: Expose a workspace type with GET_SINGLE, GET_MULTI, POST, PATCH, DELETE methods. Map important attributes, make name/title queryable, use referenceConversion(UID) for reference attributes.
2. **Read-only resource**: Expose a type with GET_SINGLE, GET_MULTI only. Useful for lookup data or master data.
3. **Workspace-scoped search**: Set resource search to filter by both type and workspace — ensures API users can only access the intended data.
4. **Multiple schemas per endpoint**: Group logically related types under one endpoint path (e.g., "v1") with separate resource paths per type.

### Integration with AI Builder

- `building-blocks-plan` selects this app when requirements mention REST API, external access, or integrations
- `workspace-setup` installs the app into the workspace
- `rest-endpoint-plan` designs the endpoint structure (which types to expose, attribute mappings, methods)
- `rest-endpoint-build` creates the configuration pages via `cplace_manage_page` in dependency order

### Important Constraints

- Always create entities in order: Endpoint → Schema → Attribute → Conversion → Resource
- Enable the endpoint LAST (after all configuration is complete)
- Leave `productionMode` = false during AI Builder sessions
- The `cf.cplace.rest.search` attribute on Resource requires a serialized cplace search constraint