CRUD generator endpoints

These endpoints allow you to among other things generate CRUD HTTP backend modules, and are at the heart of the Endpoint Generator. In addition these endpoints allow you to generate SQL based HTTP endpoints. These endpoints are not intended for being directly invoked by your code, but rather from the Magic dashboard as it is creating backend endpoints for you.

Backend CRUD operations

This section describes the parts that generate backend HTTP endpoints for you, typically wrapping a database table with CRUD operations.

POST magic/system/crudifier/crudify

This endpoint creates one CRUD HTTP endpoint for you, wrapping the specified database table with the specified HTTP verb/CRUD-operation. The endpoint requires the following payload.

{
  "verbose": true,
  "join": true,
  "databaseType": "xxx",
  "moduleName": "xxx",
  "database": "xxx",
  "table": "xxx",
  "moduleUrl": "xxx",
  "returnId": true,
  "template": "xxx",
  "verb": "xxx",
  "auth": "xxx",
  "log": "xxx",
  "overwrite": true,
  "validators": "xxx",
  "cache": 42,
  "publicCache": true,
  "cqrs": true,
  "cqrsAuthorisation": "xxx",
  "cqrsAuthorisationValues": "xxx",
  "args": "*",
  "conditions": "*"
}

The above fields imply the following.

  • [verbose] - If true more query parameter types will be generated for your GET/read endpoint
  • [paging] - If true, paging query parameters (limit and offset) are generated for your GET/read endpoint
  • [sorting] - If true, sorting query parameters (order and direction) are generated for your GET/read endpoint
  • [distinct] - If true, an additional distinct GET endpoint is generated for the table
  • [aggregate] - If true, an additional aggregate GET endpoint is generated for the table
  • [search] - If true, an additional keyword density search GET endpoint is generated for the table
  • [captcha] - If specified, requires a Magic CAPTCHA token with at least this value to invoke the endpoint
  • [join] - If true, joins will be automatically applied for the endpoint
  • [databaseType] - Type of database, such as for instance ‘pgsql’, ‘mssql’, or ‘mysql’
  • [moduleName] - The root URL of your endpoint
  • [database] - Name of database, and connection string, e.g. [generic|sakila]
  • [table] - Name of table to wrap
  • [moduleUrl] - Secondary part of your CRUD endpoint’s URL
  • [returnId] - Only relevant for POST/create endpoints, but if true will return the ID of the newly created item
  • [template] - Full relative path of the template to use, e.g. ‘/system/crudifier/templates/crud.template.get.hl’
  • [verb] - HTTP verb to wrap, either ‘delete’, ‘get’, ‘post’ or ‘put’
  • [auth] - Comma separated list of roles allowed to invoke endpoint
  • [log] - Log entry to write upon invocation of endpoint
  • [overwrite] - If true will overwrite existing file. If false the invocation will throw an exception if the endpoint file already exists
  • [validators] - Hyperlambda code being validators for endpoint
  • [cache] - Number of seconds the GET endpoint should be cached (HTTP cache). Only relevant for GET endpoints
  • [publicCache] - Whether or not the cache will be public cache, implying possible to cache by proxies. Only relevant if above is non-zero
  • [cqrs] - If true will publish SignalR/socket messages upon invocation of endpoint
  • [cqrsAuthorisation] - Type of authorisation for SignalR messages published. Legal values are ‘inherited’, ‘roles’, ‘groups’, ‘users’ or ‘none’
  • [cqrsAuthorisationValues] - If the above is supplied, these are the comma separated values defining their values. For instance, if you’re using “roles” as the above value, this is a comma separated value declaring which roles will be notified when subscribing to the message
  • [args] - These are arguments to the endpoint, implying a list of [columns] and a list of [primary] keys. Primary keys are only relevant for PUT and DELETE endpoints, but columns is a list of objects with “name” and “type” values.
  • [conditions] - This is a list of optional query parameters and are only relevant to GET endpoints. If specified it completely overrides the existing query parameters generated automatically by Magic.

The CRUD endpoints to HTTP verb mappings this endpoint generates are as follows.

  • Create - HTTP POST verb
  • Read - HTTP GET verb
  • Read(count) - HTTP GET verb with -count postfix in URL
  • Update - HTTP PUT verb
  • Delete - HTTP DELETE verb

This endpoint can only be invoked by a root user. This endpoint is to be considered obsolete and will probably change in a future version of Magic. This endpoint is not intended for you to consume in your own code.

POST magic/system/crudifier/custom-sql

This endpoint creates an SQL based HTTP endpoint for you. It’s similar to the above endpoint, but much simpler in syntax. It requires the following payload.

{
  "databaseType": "xxx",
  "authorization": "xxx",
  "moduleName": "xxx",
  "database": "xxx",
  "arguments": "xxx",
  "verb": "xxx",
  "endpointName": "xxx",
  "sql": "xxx",
  "overwrite": true
}

The arguments imply the following.

  • [databaseType] - Database type your SQL is wrapping. E.g. ‘mysql’, ‘pgsql’ or ‘mssql’
  • [authorization] - Comma separated list of roles allowed to invoke the endpoint
  • [moduleName] - Primary URL of endpoint
  • [database] - Name of database, and connection string, e.g. [generic|sakila]
  • [arguments] - Hyperlambda declaration of arguments endpoint can handle. E.g. filter:string.
  • [verb] - HTTP verb endpoint wraps. This can be any of ‘get’, ‘post’, ‘put’, ‘delete’, and ‘patch’
  • [endpointName] - Secondary URL for endpoint
  • [sql] - Actual SQL executed as endpoint is executing
  • [overwrite] - If true invocation will overwrite any existing file, otherwise the invocation will throw an exception if the endpoint file already exists

The endpoint can only be invoked by a root user. This endpoint is not intended for you to consume in your own code.

Sandbox and search endpoints

These two endpoints power the “Sandbox API” and “Search endpoint” tabs of the Endpoint Generator. Both generate one endpoint file from a template, inject the settings you chose into it, and can only be invoked by a root user. They are not intended for you to consume in your own code.

POST magic/system/crudifier/sandbox-api

Creates one Hyperlambda endpoint that executes code its own callers supply, inside a whitelist chosen from the caller’s roles. It requires the following payload.

{
  "moduleName": "xxx",
  "endpointName": "xxx",
  "verb": "post",
  "inputMode": "both",
  "authorization": "xxx",
  "policy": "xxx",
  "overwrite": true
}
  • [moduleName] and [endpointName] - Primary and secondary URL of the endpoint
  • [verb] - HTTP verb, one of ‘post’, ‘get’, ‘put’, ‘delete’ or ‘patch’
  • [inputMode] - What the endpoint accepts. ‘hl’ for Hyperlambda, ‘nl’ for natural language, or ‘both’
  • [authorization] - Comma separated list of roles allowed to invoke the endpoint. Empty makes it public
  • [policy] - A JSON string holding the settings - overrideRoot, returnCode, generatorUrl, and a list of rules, each with a role, its slots, an optional description, and optionally a limit, window and timeout
  • [overwrite] - If true any existing file is overwritten, otherwise the invocation throws if the file exists

Besides saving the endpoint, the invocation lists it in the “/etc/www/.well-known/hyperlambda-agent” discovery file, creating the folder and the file pair from templates if they do not yet exist. The endpoint that is generated accepts a [describe] argument, which returns what the caller may do instead of executing code.

POST magic/system/crudifier/search-api

Creates one Hyperlambda endpoint that searches the training snippets of a single machine learning type. It requires the following payload.

{
  "moduleName": "xxx",
  "endpointName": "xxx",
  "verb": "get",
  "type": "xxx",
  "retrieval": "",
  "threshold": 0.3,
  "limit": 5,
  "uri": "",
  "meta": "",
  "result": "references",
  "authorization": "xxx",
  "rateLimit": 20,
  "rateWindow": 60,
  "cacheSeconds": 0,
  "overwrite": true
}
  • [moduleName] and [endpointName] - Primary and secondary URL of the endpoint
  • [verb] - HTTP verb, either ‘get’ or ‘post’
  • [type] - The machine learning type to search. It must exist
  • [retrieval] - ‘bm25’ for keyword search, ‘mixed’ for keyword and meaning, ‘embeddings’ for meaning, or empty to use the type’s own setting
  • [threshold] - Optional similarity cutoff. Omit it to use the type’s own
  • [limit] - The most matches the endpoint returns
  • [uri] and [meta] - Optional filters, where the meta is a pattern in which % matches any text
  • [result] - ‘references’ returns the prompt and URI of each match, ‘rows’ also returns its completion and meta
  • [authorization] - Comma separated list of roles allowed to invoke the endpoint. Empty makes it public
  • [rateLimit] and [rateWindow] - Calls an IP may make per window of seconds, root excepted. 0 means no limit
  • [cacheSeconds] - How long the caller may cache an answer, sent as a Cache-Control header
  • [overwrite] - If true any existing file is overwritten, otherwise the invocation throws if the file exists