Generated API Reference

Name: Artificial Interface
Author: Björn Berger

This page documents the current data-driven API contract of Artificial Interface. Its endpoint patterns are deliberately relational and CRUD-oriented; domain logic and product-specific security rules must be modeled and reviewed separately.

API Standards

OpenAPI 2.0: Follows the Swagger 2.0 specification and supports APIs based on RESTful principles. The specification provides a standardized, language-independent interface that allows humans and machines to understand a service without access to source code or network traffic.

OpenAPI 3.0: Supports modern OpenAPI standards and adds improvements over version 2.0, including callbacks, links, and more flexible security definitions.

Authentication: Uses API-Key authentication with the key provided in the x-api-key request header. This validates the client through a unique API key.

Common Patterns Across Endpoints

CRUD Operations: Provides Create, Read, Update, and Delete operations for managing the full lifecycle of data entities directly through the API.
Endpoint Naming: Uses a straightforward naming convention /schema_name/entity for endpoint paths, enhancing clarity and consistency across the API. This helps in logically organizing the API's resources and makes the endpoints predictable and intuitive to use.
Responses and Status Codes: Uses HTTP status codes to communicate success, failure, and error states. Common codes include 200 for successful operations, 400 for bad requests, 401 for unauthorized requests, and 500 for internal server errors.
Query Parameters for Filtering and Pagination: Supports efficient data retrieval through query parameters, allowing for filtering based on specific attributes and pagination to manage large data sets. This provides clients with the flexibility to request exactly what they need, optimizing data access and transfer.
Path Variables for Specific Entities: Allows direct operations on specific entities via path variables, enabling actions like retrieving or deleting an entity based on its unique identifier within the URL path.
Atomic Transaction Workflows: Executes an explicit, versioned and ordered set of allowlisted CRUD operations in one native database transaction.
Use of Extended Properties: The API uses extended properties like x-database-schema and x-database-table, which are not part of the standard OpenAPI specification. These provide a clear mapping to underlying database structures, making the API more integrated with its backend storage layer.

Schema Definitions and Relationships

Each data entity includes detailed schema definitions that reflect the relational database model. These definitions describe field types, required fields, unique constraints, and relationships to other entities, helping developers model and use the data correctly.

Unified API Design Principles

Entity Lifecycle Management: Each data entity comes with intuitive CRUD operation mappings.
Customizable Data Retrieval: Implements flexible query parameters and sorting mechanisms.
Uniform Operation Interface: Ensures clear and predictable feedback through standardized HTTP status codes.
Versioned Transaction Contract: Uses typed step bodies and RFC 6901 bindings to pass values from earlier results into later steps.

POST Transaction Workflow

The generated API exposes POST /transaction as a versioned, ordered and atomic workflow. The request uses contractVersion: 1 and an explicit steps array; the former top-level transaction array is rejected.

{
  "contractVersion": 1,
  "steps": [
    {
      "id": "create-parent",
      "operation": "main.parent.post",
      "body": [{ "name": "Parent" }]
    },
    {
      "id": "create-child",
      "operation": "main.child.post",
      "body": [{ "name": "Child" }],
      "bindings": [{
        "target": "/0/id_parent",
        "source": { "step": "create-parent", "path": "/0/id" }
      }]
    }
  ]
}

Steps run in array order and may reference only earlier results.
Bindings use RFC 6901 JSON Pointers and keep operation bodies typed.
All steps share one native database transaction; success is returned only after commit.
Validation, binding, driver, timeout or commit failures stop later steps and trigger rollback.

The GraphQL runtime uses this REST workflow internally for typed nested POST/PATCH mutations, but does not expose a second generic GraphQL transaction mutation. Clients may call the REST endpoint directly.

GET Endpoint Structure

GET endpoints are designed to retrieve existing data about entities within the API's `schema_name` schema. These endpoints allow clients to query and obtain information on entities based on specific criteria or retrieve details of a particular entity by its identifier.

Get by ID: For querying entities based on criteria or retrieving all entities of a specific type, the GET requests are made to /schema_name/entity. To retrieve a specific entity by its identifier, the request is made to /schema_name/entity/{id}, where `{id}` is the unique identifier of the entity.

Get: Query parameters can be used to filter the list of entities returned by the GET request. Common parameters could be `name`, `email`, `phone`, and date range filters like `created` and `modified`. The use of these parameters allows for refined searches tailored to the client's needs.

Example:

GET /schema_name/entity?name=JohnDoe&email=john@example.com HTTP/1.1

Headers:

While GET requests primarily focus on retrieving data and may not require a body, it is essential to include any necessary headers for authentication. The x-api-key header should be included with the client's API key for secure access.

Responses and Status Codes:

200 OK: The request was successful, and the response body contains the requested data about the entities.
400 Bad Request: The request cannot be processed, often due to invalid query parameters.
401 Unauthorized: Authentication has failed, likely due to an incorrect or missing API key.
500 Internal Server Error: An internal server error occurred, often because of server-side problems.

Example:

GET /schema_name/entity?email=john@example.com HTTP/1.1
Host: 127.0.0.1
x-api-key: YourApiKeyHere

This example demonstrates a GET request to query entities based on the `email` attribute within the `schema_name` schema.

OpenAPI Example:

This example illustrates how the generated GET requests are represented in the OpenAPI documentation.

{
    "/schema_name/entity": {
        "get": {
            "x-swagger-router-controller": "GenericController",
            "x-database-schema": "schema_name",
            "x-database-table": "entity",
            "description": "GET",
            "operationId": "schema_name.entity.get",
            "parameters": [
                {
                    "name": "ID",
                    "in": "query",
                    "required": false,
                    "description": "\"ID\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "format": "int64",
                            "minimum": 1
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "STATUS",
                    "in": "query",
                    "required": false,
                    "description": "\"STATUS\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "boolean"
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "EMAIL",
                    "in": "query",
                    "required": false,
                    "description": "\"EMAIL\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "email",
                            "minLength": 5,
                            "maxLength": 255,
                            "pattern": "/^(([^<>()\\[\\]\\\\.,;:\\s@\"]+(\\.[^<>()\\[\\]\\\\.,;:\\s@\"]+)*)|(\".+\"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$/"
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "NAME",
                    "in": "query",
                    "required": false,
                    "description": "\"NAME\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 255
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "CREATED",
                    "in": "query",
                    "required": false,
                    "description": "\"CREATED\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "date-time",
                            "minLength": 1,
                            "maxLength": 255
                        },
                        "minItems": 1,
                        "maxItems": 2,
                        "uniqueItems": true
                    }
                },
                {
                    "name": "MODIFIED",
                    "in": "query",
                    "required": false,
                    "description": "\"MODIFIED\" of entity",
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "date-time",
                            "minLength": 1,
                            "maxLength": 255
                        },
                        "minItems": 1,
                        "maxItems": 2,
                        "uniqueItems": true
                    }
                },
                {
                    "name": "$select",
                    "in": "query",
                    "description": "Specify one or more properties to retrieve (horizontal filtering).",
                    "required": false,
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "id",
                                "status",
                                "email",
                                "name",
                                "created",
                                "modified"
                            ]
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "$orderBy",
                    "in": "query",
                    "description": "\"orderBy\": to order the result asc(+) or desc(-) by columns. The '+' prefix is optional.",
                    "required": false,
                    "style": "pipeDelimited",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "-id",
                                "+id",
                                "id",
                                "-status",
                                "+status",
                                "status",
                                "-email",
                                "+email",
                                "email",
                                "-name",
                                "+name",
                                "name",
                                "-created",
                                "+created",
                                "created",
                                "-modified",
                                "+modified",
                                "modified"
                            ]
                        },
                        "uniqueItems": true
                    }
                },
                {
                    "name": "$offsetId",
                    "in": "query",
                    "description": "Set offset by ID",
                    "required": false,
                    "schema": {
                        "type": "integer",
                        "format": "int64",
                        "minimum": 0
                    }
                },
                {
                    "name": "$limit",
                    "in": "query",
                    "description": "Limit the amount of fetched items and specify the amount of skipped items",
                    "required": false,
                    "style": "form",
                    "explode": false,
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "maxItems": 2
                    }
                }
            ],
            "responses": {
                "200": {
                    "description": "OK",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/schema_name.entity.get"
                                }
                            }
                        }
                    }
                },
                "400": {
                    "description": "Bad Request"
                },
                "401": {
                    "description": "Unauthorized"
                },
                "500": {
                    "description": "Internal Server Error"
                }
            },
            "summary": "Search and sort entity by its paramters. Pagination can be used also.",
            "tags": [
                "schema_name.entity"
            ]
        }
    }
}

GET Query Parameters

Various filter options are available in the API, designed to offer the flexibility to retrieve data efficiently and effectively. These filtering options include basic filtering, searching by multiple values, range search for dates, LIKE operations on string data types, and combined searches.

Horizontal Filtering

Horizontal filtering allows the filtering of attributes before the entity is retrieved.

Usage: Append the $select keyword and the needed attribute names to the query parameters in your GET request.
Example: To retrieve entities with only specific attributes, your request could look like this:
```
GET /entity?$select=email|name|status HTTP/1.1
```
SQL Equivalent:
```
SELECT email, name, status FROM entity;
```

Vertical Filtering

Vertical filtering allows for the retrieval of entities based on exact matches of their attributes.

Usage: Append the attribute and its desired value to the query parameters in your GET request.
Example: To retrieve entities with a specific status, your request could look like this:
```
GET /entity?status=true HTTP/1.1
```

SQL Equivalent:

SELECT * FROM entity WHERE status = true;

Searching by Multiple Values

The API supports filtering by multiple values for both numeric and string attributes. This feature enables fetching entities that match any of the specified values.

Usage: Separate multiple values with a pipe (|) in the query parameters.
Example: To retrieve entities where numberAttribute is either 1, 2, or 3:
```
GET /entity?numberAttribute=1|2|3 HTTP/1.1
```

SQL Equivalent:

SELECT * FROM entity WHERE numberAttribute IN (1, 2, 3);

Range Search for Dates

Range searches allow you to retrieve entities based on a date range, useful for filtering entities created or modified within specific timeframes.

Usage: Specify the start and end dates separated by a pipe (|). The dates should follow the ZULU time format.
Example: To filter entities created between January 1, 2023, and December 31, 2023, in ZULU time format:
```
GET /entity?created=2023-01-01T00:00:00Z|2023-12-31T23:59:59Z HTTP/1.1
```

SQL Equivalent:

SELECT * FROM entity WHERE created BETWEEN '2023-01-01T00:00:00Z' AND '2023-12-31T23:59:59Z';

Like Operation on String Data Types

The LIKE operation offers pattern matching for string attributes, following the SQL LIKE syntax. It's ideal for searching text fields when you don't have exact match criteria.

Usage: Use % as a wildcard for any sequence of characters, and _ for any single character.
Example: To find entities where name contains "abc" or "xyz":
```
GET /entity?name=%abc%|%xyz% HTTP/1.1
```

SQL Equivalent:

SELECT * FROM entity WHERE name LIKE '%abc%' OR name LIKE '%xyz%';

Combined Searches

The API supports combining multiple filter types in a single query, enabling precise control over the data retrieved.

Usage: Combine different filtering options in your query parameters as needed.
Example: To perform a combined search for entities created in 2023 with a status of true and a name containing "abc" or "xyz":
```
GET /entity?created=2023-01-01T00:00:00Z|2023-12-31T23:59:59Z&status=true&name=%abc%|%xyz% HTTP/1.1
```

SQL Equivalent:

SELECT * FROM entity 
WHERE created BETWEEN '2023-01-01T00:00:00Z' AND '2023-12-31T23:59:59Z' 
AND status = true 
AND (name LIKE '%abc%' OR name LIKE '%xyz%');

GET Pagination

Efficient data retrieval in applications that handle large volumes of data is crucial. The API implements advanced pagination techniques allowing for effective data management and retrieval by segmenting data into manageable chunks.

Pagination Techniques

This guide assumes that each resource in the API has at a minimum an id and a created column where id is an integer and created a date-time type.

1. Offset Pagination with Sorting

Use Case: Best suited for ordered data retrieval while controlling the starting point based on item IDs.
Parameters:
- $limit: The maximum number of items to return.
- $offsetId: Excludes items where the "id" is less than or equal to the specified $offsetId.
- $orderBy: Specifies the column to sort by. Use - for descending order.

Example:

GET /schema/table?$limit=10&$offsetId=20&$orderBy=-id HTTP/1.1

SQL Equivalent:

SELECT * FROM schema.table WHERE id > 20 ORDER BY id DESC LIMIT 10;

2. Combined Limit and Offset

Use Case: Simplifies request syntax by combining the page size and starting offset into one parameter.
Parameters:
- $limit: A composite parameter where the first number is the page size and the second is the offset count.
Example:
```
GET /schema/table?$limit=20,10 HTTP/1.1
```

SQL Equivalent:

SELECT * FROM schema.table LIMIT 10 OFFSET 20;

3. Filtering with Pagination and Sorting

Use Case: Retrieves data based on specific filters with support for pagination and sorting.
Parameters:
- $limit: Sets the maximum number of items returned.
- $orderBy: Determines the order of the results.
- Filter Parameters: Additional parameters for filtering.

Example:

GET /schema/table?$limit=10&$orderBy=-created&created=2023-03-23|2025-03-23 HTTP/1.1

SQL Equivalent:

SELECT * FROM schema.table WHERE created BETWEEN DATE('2023-03-23T17:42:00.667Z') AND DATE('2025-03-23T17:42:06.107Z') ORDER BY created DESC LIMIT 10;

Pagination Key Considerations

Understanding $offsetId: Functions by excluding records with an ID less than the specified value.
Using $offsetId for Efficiency: More efficient than numeric offsets for large datasets.
Use filtering parameters alongside $limit and $orderBy to finely tune data retrieval.
Choose page size to balance granularity of data retrieval and performance.
Provide navigational controls for easy page movement in a UI.

POST Endpoint Structure

POST endpoints are designed for the creation of new instances of data entities within the API's `schema_name` schema. These endpoints enable clients to submit new data records for creation, expanding the dataset with new entities as needed.

Endpoint Naming and Path:

The POST requests target the endpoint following the pattern /schema_name/entity, indicating the creation of new entities within the specified schema. This naming convention ensures that the API's structure remains clear and consistent.

Request Body Structure:

The request body must contain all the necessary attributes required to create new entities, as defined by the entity’s schema. This includes specifying values for all required fields and adhering to any defined data types and constraints.

Batch operations are also supported. Include multiple entities in the request body to create them in a single request.

[
  {
    "name": "New Entity Name",
    "attribute1": "Value1",
    "attribute2": "Value2"
  },
  {
    "name": "Another Entity Name",
    "attribute1": "Value3",
    "attribute2": "Value4"
  }
]

Note: Replace "attribute1", "attribute2", etc., with the actual attribute names and values relevant to the entity being created.

Headers:

Every POST request must include the Content-Type: application/json header to indicate the format of the request body. Authentication is managed through the inclusion of the x-api-key header, containing the API key provided to the client.

Responses and Status Codes:

200 OK: The entity was successfully created. The response body usually includes the newly created entity, including its unique identifier and any other relevant information.
400 Bad Request: The request could not be processed, typically due to missing required fields or data that does not comply with the entity’s schema.
401 Unauthorized: Indicates that authentication has failed, which may be due to an incorrect or missing API key.
500 Internal Server Error: An internal server error occurred, often because of server-side problems.

Example:

This example shows how to construct a POST request to create a new entity within the `schema_name` schema, including specifying attribute names and values.

POST /schema_name/entity HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json
x-api-key: YourApiKeyHere

[{
  "name": "New Entity Name",
  "attribute1": "Value1",
  "attribute2": "Value2"
}]

OpenAPI Example:

This example illustrates how the generated POST requests are represented in the OpenAPI documentation.

{
    "/schema_name/entity": {
        "post": {
            "x-swagger-router-controller": "GenericController",
            "x-database-schema": "schema_name",
            "x-database-table": "entity",
            "description": "POST",
            "operationId": "schema_name.entity.post",
            "requestBody": {
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/schema_name.entity.post"
                            }
                        }
                    }
                },
                "description": "Create entity",
                "required": true
            },
            "responses": {
                "200": {
                    "description": "OK",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/schema_name.entity.post"
                                }
                            }
                        }
                    }
                },
                "400": {
                    "description": "Bad Request"
                },
                "401": {
                    "description": "Unauthorized"
                },
                "500": {
                    "description": "Internal Server Error"
                }
            },
            "summary": "POST Request to create one or more entity",
            "tags": [
                "schema_name.entity"
            ]
        }
    }
}

PATCH Endpoint Structure

The PATCH endpoints are designed to update existing instances of data entities within the API. Unlike PUT, PATCH applies partial modifications to a resource. It requires the "id" of the entity to be included in the request, along with any fields that need updating. This approach allows for the specific fields of an entity to be updated without resubmitting the entire entity.

Endpoint Naming and Path:

PATCH requests are made to the endpoint following the pattern /schema_name/entity. This endpoint is used for idempotent operations, where providing the same "id" and data in multiple requests results in the same state of the entity without creating duplicates.

Request Body Structure:

The request body for a PATCH endpoint must include the "id" of each entity being updated, along with the fields that should change. You do not need to include every attribute. The "id" belongs in the body rather than the path because a single request can update multiple items.

[
  {
	"id": 123,
	"name": "Updated Entity Name",
	"email": "updated_email@example.com"
  },
  {
    "id": 456,
    "name": "Another Updated Entity Name",
    "email": "another_updated_email@example.com"
  }
]

Headers:

All PATCH requests must include the Content-Type: application/json header. Authentication is handled through the x-api-key header, which must contain the client's API key.

Responses and Status Codes:

200 OK: The entity was successfully updated.
400 Bad Request: The request body does not match the entity's schema, violates constraints, or the "id" is missing.
401 Unauthorized: Authentication failed, likely due to an invalid API key.
500 Internal Server Error: An internal server error occurred, often because of server-side problems.

Example:

This example demonstrates a PATCH request that updates specific fields of an entity, using its "id" for identification.

PATCH /schema_name/entity HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json
x-api-key: YourApiKeyHere

[{
  "id": 123,
  "name": "Updated Entity Name",
  "email": "updated_email@example.com"
}]

OpenAPI Example:

This example illustrates how the generated PATCH requests are represented in the OpenAPI documentation.

{
    "/schema_name/entity": {
        "patch": {
            "x-swagger-router-controller": "GenericController",
            "x-database-schema": "schema_name",
            "x-database-table": "entity",
            "description": "PATCH",
            "operationId": "schema_name.entity.patch",
            "requestBody": {
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/schema_name.entity.patch"
                            }
                        }
                    }
                },
                "description": "Modify entity",
                "required": true
            },
            "responses": {
                "200": {
                    "description": "OK",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/schema_name.entity.patch"
                                }
                            }
                        }
                    }
                },
                "400": {
                    "description": "Bad Request"
                },
                "401": {
                    "description": "Unauthorized"
                },
                "500": {
                    "description": "Internal Server Error"
                }
            },
            "summary": "PATCH Request to update one or more entity. A PATCH request is idempotent, updating parts of a resource without full replacement.",
            "tags": [
                "schema_name.entity"
            ]
        }
    }
}

DELETE Endpoint Structure

DELETE endpoints are designated for removing existing entities. This operation allows clients to delete specific entities by their unique identifiers, ensuring data that is no longer needed can be appropriately managed and removed.

Endpoint Naming and Path:

DELETE requests target the endpoint /schema_name/entity/{id}, where `{id}` is the unique identifier of the entity to be deleted. This convention ensures precise targeting of the entity intended for deletion.

Headers:

All DELETE requests must include necessary headers for authentication. This typically involves the x-api-key header containing the client's API key, ensuring that only authorized users can delete entities.

Responses and Status Codes:

200 OK: Indicates the entity was successfully deleted.
400 Bad Request: The request was malformed, often due to an incorrect entity ID format.
401 Unauthorized: Authentication failed due to an incorrect or missing API key.
500 Internal Server Error: An internal server error occurred, often because of server-side problems.

Example:

DELETE /schema_name/entity/123 HTTP/1.1
Host: 127.0.0.1
x-api-key: YourApiKeyHere

This example illustrates a DELETE request aimed at removing an entity identified by the ID `123` within the `schema_name` schema.

OpenAPI Example:

This example illustrates how the generated DELETE requests are represented in the OpenAPI documentation.

{
    "/schema_name/entity": {
        "delete": {
            "x-swagger-router-controller": "GenericController",
            "x-database-schema": "schema_name",
            "x-database-table": "entity",
            "description": "DELETE by ID",
            "operationId": "schema_name.entity.deleteById",
            "parameters": [
                {
                    "name": "ID",
                    "description": "Delete entity by ID",
                    "required": true,
                    "in": "path",
                    "style": "simple",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "format": "int64",
                            "minimum": 1
                        },
                        "uniqueItems": true
                    }
                }
            ],
            "responses": {
                "200": {
                    "description": "OK"
                },
                "400": {
                    "description": "Invalid ID supplied"
                },
                "401": {
                    "description": "Unauthorized"
                },
                "500": {
                    "description": "Internal Server Error"
                }
            },
            "summary": "DELETE Request to delete one or more entity by ID",
            "tags": [
                "schema_name.entity"
            ]
        }
    }
}

Summary

This documentation explains the API structure, supported operations, and data access patterns. It covers CRUD operations, filtering, pagination, authentication, and the versioned transaction workflow so developers can build scalable, data-driven applications on a consistent OpenAPI foundation.

Author: Björn Berger

Email: bjoernberger.io@gmail.com