Namespaces

A namespace groups endpoints (e.g. CRM, Finance, Account). It is the folder between the endpoint type folder and the endpoint folder, and it becomes a URL segment. All endpoint types support namespaces; webhooks require one.

Directory structure ​

Folder layout per endpoint type: Entity configuration. Composite endpoints are stored under Proxy/ with "Type": "Composite".

Namespace resolution ​

The explicit Namespace takes precedence over the folder. Nested namespaces route as /api/{env}/WMS/Inbound/StagingBins, form a tag with parent: WMS in the OpenAPI document, and nest in the /docs sidebar. The longest matching path wins: with WMS/Bins and WMS/Inbound/StagingBins configured, /api/{env}/WMS/Inbound/StagingBins resolves the nested endpoint. Example: WMS/Inbound/StagingBins in the SQLite demo environment.

Properties ​

{
  "Namespace": "Finance",
  "NamespaceDisplayName": "Financial Management System",
  "NamespaceDescription": "Ledgers, invoices and payments.",
  "DisplayName": "General Ledger Entries"
}

Routes ​

GET    /api/{env}/{namespace}/{endpoint}
GET    /api/{env}/{namespace}/{endpoint}/{id}
POST   /api/{env}/{namespace}/{endpoint}
PUT    /api/{env}/{namespace}/{endpoint}/{id}
DELETE /api/{env}/{namespace}/{endpoint}/{id}

Examples: /api/prod/Account/Contacts, /api/prod/Finance/Transactions/12345.

Endpoints without a namespace use /api/{env}/{endpoint} and /api/{env}/{endpoint}/{id}. File endpoints use /api/{env}/files/{namespace}/{endpoint}; returned download URLs include the namespace. Composite endpoints are also reachable at /api/{env}/composite/{endpoint}.

Versions ​

A v{n} folder (v1 to v999) below an endpoint folder holds that version of the endpoint. Without a v1 folder, the endpoint folder's own entity.json is v1.

endpoints/SQL/Inventory/Products/
├── entity.json        → /api/{env}/Inventory/Products  (also /api/{env}/v1/Inventory/Products)
└── v2/
    └── entity.json    → /api/{env}/v2/Inventory/Products

The OpenAPI document lists every version under the endpoint's tag, with the version appended to the operation summary and operationId. /docs/openapi/v{n}/openapi.json holds one version; /docs offers a version switch when more than one version exists.

Retiring a version ​

{
  "Deprecated": true,
  "DeprecatedSince": "2026-10-01T00:00:00Z",
  "Sunset": "2027-04-01T00:00:00Z"
}

The console's New version action copies entity.json and its sibling files into the next v{n} folder. A base endpoint with versions is deleted after its versions; a version is renamed through its base endpoint.

Example ​

/endpoints/SQL/Company/Employees/entity.json:

{
  "DatabaseObjectName": "Employees",
  "DatabaseSchema": "hr",
  "PrimaryKey": "EmployeeID",
  "AllowedColumns": ["EmployeeID", "FirstName", "LastName", "Department", "HireDate"],
  "Namespace": "Company",
  "NamespaceDisplayName": "Company Management",
  "DisplayName": "Employee Records",
  "AllowedEnvironments": ["dev", "test", "prod"]
}

A composite step names a namespaced endpoint by its path, e.g. "Endpoint": "Account/Customers".

Naming rules ​

Per segment of a namespace:

Reserved names: api, docs, openapi, health, admin, system, composite, webhook, files. An endpoint with a reserved or invalid namespace is not loaded, and the console refuses to save it.

OpenAPI tags ​

Endpoint tags are named by the route below /api/{env}: {namespace}/{endpoint} for a namespaced endpoint, {endpoint} without a namespace, files/{endpoint} for a file endpoint. Group tags are named ns:{namespace} and have kind: nav. Endpoint tags have no kind. Each endpoint tag sets parent to its group, and a nested group sets parent to the group one segment up. The ns: prefix separates a group from an endpoint of the same name. Labels set the sidebar title (summary) and never change a tag name.

An endpoint without a namespace is placed in the ns:{DefaultGroup} group (OpenApi:DefaultGroup, default General), a file endpoint without a namespace in ns:Files. With an empty DefaultGroup an endpoint without a namespace has no parent. With OpenApi:ShowNamespaces set to false no group tags are declared and no tag has a parent.

Endpoints in one namespace should share one NamespaceDisplayName and one NamespaceDescription. Set them on every endpoint in the namespace or on one. With conflicting values the ordinal first value is used, and startup logs a warning naming the namespace, the setting and its values.

Within each group, endpoints are listed before subgroups, each ordered by title. A namespace named like DefaultGroup shares its group.

{
  "tags": [
    { "name": "ns:CRM", "summary": "Customer Relationship Management", "kind": "nav", "description": "Customers, contacts and suppliers." },
    { "name": "CRM/Accounts", "summary": "Accounts", "parent": "ns:CRM", "description": "Account Management" },
    { "name": "CRM/Suppliers", "summary": "Vendors", "parent": "ns:CRM" }
  ]
}

Troubleshooting ​

Related topics ​

• Entity Configuration
• Folders and Routes
• API Overview