# App Runtime REST API

The **App Runtime** in ONEWEB provides a set of **REST APIs** that allow external systems to interact with applications built using **App Designer**.

These APIs enable external clients to **insert, update, retrieve, and delete entity data** defined in App Designer, as well as manage file upload and download operations.

Using App Runtime REST APIs, ONEWEB applications can act as **backend services** consumable by other systems.

***

### Purpose of App Runtime REST API

The App Runtime REST APIs are designed to:

* Expose **App Designer entities** as RESTful services
* Enable system‑to‑system integration
* Allow external clients to manage application data
* Support CRUD operations without UI dependency
* Enable file upload and download via REST

These APIs provide a standardized way to integrate ONEWEB applications into broader enterprise architectures.

***

### Authentication

Before calling most App Runtime APIs, users must authenticate and obtain a **token ID**.

#### Login API

| Endpoint | Description                      | Method   |
| -------- | -------------------------------- | -------- |
| `/login` | Login process to obtain token ID | **POST** |

The returned token must be included in subsequent API calls according to the security configuration of the runtime.

***

### Entity REST APIs

The following APIs allow external systems to interact with **Entities** created in App Designer.

#### Search Entity Data

| Endpoint                    | Description                                                                        | Method  |
| --------------------------- | ---------------------------------------------------------------------------------- | ------- |
| `/entity/{entityID}/search` | Search data in `{entityID}` using URL parameters and return results in JSON format | **GET** |

***

#### Get Entity Data

| Endpoint                 | Description                                              | Method  |
| ------------------------ | -------------------------------------------------------- | ------- |
| `/entity/{entityID}/get` | Retrieve entity data in JSON format using key parameters | **GET** |

***

#### Save Entity Data

| Endpoint                  | Description                                              | Method   |
| ------------------------- | -------------------------------------------------------- | -------- |
| `/entity/{entityID}/save` | Save entity data provided as JSON body into the database | **POST** |

***

#### Delete Entity Data

| Endpoint                    | Description                                | Method   |
| --------------------------- | ------------------------------------------ | -------- |
| `/entity/{entityID}/delete` | Delete entity data based on key parameters | **POST** |

***

#### Save Parent–Child Entity Structure

| Endpoint                                 | Description                                                               | Method   |
| ---------------------------------------- | ------------------------------------------------------------------------- | -------- |
| `/entities/save?mainEntityID={entityID}` | Save parent and child entity data (tab‑based structure) into the database | **POST** |

This endpoint is typically used when entities are configured with **parent‑child relationships** in App Designer.

***

### File Management REST APIs

App Runtime also provides APIs for file upload and download.

***

#### Upload File

| Endpoint       | Description                                           | Method   |
| -------------- | ----------------------------------------------------- | -------- |
| `/file/upload` | Upload a file to the server based on configured rules | **POST** |

***

#### Download File

| Endpoint              | Description                                          | Method  |
| --------------------- | ---------------------------------------------------- | ------- |
| `/file/{id}/download` | Download a previously uploaded file using its `{id}` | **GET** |

***

### API Invocation Pattern

All App Runtime APIs are invoked by appending the endpoint to the **context root** of the runtime server.

Example (conceptual):

```
https://<runtime-host>/<context-root>/entity/{entityID}/get
```

Headers, authentication tokens, and request body formats depend on the runtime configuration and security setup.

***

### Best Practices

* Always authenticate before accessing entity APIs
* Validate entity structure before sending JSON payloads
* Use search APIs for filtered queries instead of retrieving all records
* Handle error responses gracefully
* Secure APIs with appropriate authentication and authorization
* Avoid exposing sensitive entities without access control

***

### Summary

The **App Runtime REST API** enables ONEWEB applications to expose App Designer entities as **REST‑based services**.

Using these APIs, external systems can:

* Authenticate and interact with ONEWEB applications
* Perform CRUD operations on entity data
* Handle parent‑child entity structures
* Upload and download files programmatically

App Runtime REST APIs play a critical role in enabling **system‑to‑system integration** and positioning ONEWEB applications as reusable backend services.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onewebstack.com/oneweb-platform-th/building-apps/integrations/app-runtime-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.