Overview

Introduction

ORDA (Object Relational Data Access) allows developers to interact with the data model of an application through REST APIs. Class functions defined in the ORDA data model and singleton class functions can be exposed and called via REST requests. This allows external systems and clients to leverage the data and business logic encapsulated within an application.

Prerequisites

exposed Functions

Only functions marked with the exposed keyword can be called from REST requests. This ensures that only intended functions are available for external access.

Example: Exposing a Function

exposed function getTest() : string
    return "test"

info

For more details, refer to the section on Exposed vs. Non-Exposed Functions.

onHttpGet Functions

Functions allowed to be called from HTTP GET requests must also be specifically declared with the onHttpGet keyword. For example:

//allowing GET requests
exposed onHttpGet function getSomeInfo() : 4D.OutgoingMessage

Key Concepts

Function Call Syntax

Functions are called using POST or GET requests on the appropriate ORDA interface without parentheses. The URL and body of the request vary depending on the type of class function being called.

POST {{ApiEndpoint}}/rest/Product/getProductDetails

POST requests provide a better security level because they avoid running sensitive code through an action as simple as clicking on a link. However, GET requests can be more compliant with user experience, allowing to call functions by entering an URL in a browser (note: the developer must ensure no sensitive action is done in such functions).

Handling Non-Exposed Functions

If a class function is not marked as exposed, it is treated as an attribute rather than a function, resulting in an error response.

{
    "__ERROR": [
        {
            "message": "The \"getProductDetails\" attribute cannot be found in The \"Product\" dataclass",
            "componentSignature": "dbmg",
            "errCode": 1500
        },
        {
            "message": "Cannot completely build a list of attributes with \"getProductDetails\" for the \"Product\" dataclass",
            "componentSignature": "dbmg",
            "errCode": 1804
        }
    ]
}

REST API Endpoints

The ORDA REST API provides several endpoints to call class functions:

Class function	Syntax
Datastore Class	/rest/$catalog/DataStoreClassFunction
Dataclass Class	/rest/{{dataClass}}/DataClassClassFunction
EntitySelection Class	/rest/{{dataClass}}/EntitySelectionClassFunction
Entity Class	/rest/{{dataClass}}(key)/EntityClassFunction
Singleton class	/rest/$singleton/SingletonClass/SingletonClassFunction (see $singleton page)

Calling Dataclass or Entity Selection Functions

The endpoint {{ApiEndpoint}}/rest/{{dataClass}}/Function is versatile and can be used to call either a dataclass function or an entity selection function. When making a call to this endpoint, the following process is followed to determine which function to execute:

1. Entity Selection Search: The REST API first checks if the function exists in the entity selection class associated with the specified dataClass.

2. Dataclass Search: If the function is not found in the entity selection class, the API then searches for the function in the dataClass itself.

3. Function Execution:

   • If the function is found in the entity selection class, it is executed with the context of the entity selection.

   • If the function is not found in the entity selection class but exists in the dataClass, it is executed with the context of the dataClass.

   • If the function exists in both the dataClass and the entity selection class, the function in the entity selection class will be executed, and the dataclass function will be ignored. This prioritization ensures that operations intended for collections of entities are given precedence over those intended for individual entities or the dataClass structure.

4. Fallback Behavior: If the function is not found in either the entity selection class or the dataClass, an error is returned indicating that the function does not exist.

Use Case

Step 1: Defining and Exposing a Function

Consider a scenario where we have a Customer dataClass with a function to retrieve customer details based on their ID:

exposed function getCustomerDetails(customerID : Integer) : cs.CustomerEntity
    return ds.Customer.query("ID = :1", customerID).first()

In this example, the getCustomerDetails function is exposed and can be called via the REST API to fetch details of a specific customer.

Step 2: Calling the Function via REST API

To call the getCustomerDetails function for a customer with ID "123", you would use the following request:

Step 3: Request

Method: POST
URL: {{ApiEndpoint}}/rest/Customer/getCustomerDetails

Body:

[123]

Equivalent Code

This call is equivalent to:

customerDetails = ds.Customer.getCustomerDetails(123)

Step 4: Sample Response

The response from the server would look something like this:

{
    "__entityModel": "Customer",
    "__DATACLASS": "Customer",
    "__KEY": "123",
    "__TIMESTAMP": "2024-05-23T18:11:34.485Z",
    "__STAMP": 1,
    "ID": 123,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "orders": {
        "__deferred": {
            "uri": "/rest/Order?$filter=customerID=123",
            "__COUNT": 5
        }
    },
    "profilePicture": null
}

Error Handling

When making REST API calls to ORDA class functions, proper error handling should be implemented to manage cases where the function call fails or returns an unexpected result.

tip

Ensure that your client application can gracefully handle errors and retries as necessary.