getById() — Entity Service

General Description

The getById operation retrieves a single entity by its unique identifier.

Detailed Description

This operation allows you to fetch a specific entity record from the database using its unique ID. It returns the complete entity with all its properties as defined in the entity definition. This is the most direct way to retrieve a specific entity when you know its ID.

Input Parameters

Parameter	Type	Required	Description
definitionType	string	Yes*	Name or id of the entity definition.
id	string	Yes	ID of the entity to retrieve.
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Response

Success Response

{
    "success": true,
    "entity": {
        "id": "string",
        "title": "string",
        "createDate": "string",
        "lastUpdateDate": "string",
        // All other properties of the entity
        "property1": "value1",
        "property2": "value2"
    }
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Get Customer by ID

const result = await getById({
  entDefName: "Customer",
  id: "customer-id-123",
  token: "your-auth-token"
});

if (result.success) {
  const customer = result.entity;
  console.log("Customer:", customer.title);
  console.log("Email:", customer.email);
  console.log("Created:", customer.createDate);
} else {
  console.error("Error:", result.error);
}

Get Entity Using Entity Definition ID

const result = await getById({
  entDefId: "customer-def-456",
  id: "customer-id-123",
  token: "your-auth-token"
});

if (result.success) {
  const customer = result.entity;
  // Process customer data
} else if (result.error === "Entity not found") {
  console.log("Customer does not exist");
} else {
  console.error("Error:", result.error);
}

Get Entity with Optional Parameters

const result = await getById({
  entityDef: {
    name: "Product"
  },
  id: "product-id-789",
  token: "your-auth-token",
  tenantCode: "tenant1"
});

if (result.success) {
  const product = result.entity;
  console.log("Product:", product.title);
  console.log("Price:", product.price);
  console.log("In Stock:", product.inStock ? "Yes" : "No");
} else {
  console.error("Error:", result.error);
}

Additional Information

• The getById operation is used to retrieve a single entity by its unique identifier.
• The operation returns all properties of the entity as defined in the entity definition.
• If the entity does not exist, the operation will return an error with message "Entity not found".
• For retrieving multiple entities or filtering by criteria, use the query operation instead.
• For retrieving an entity with its related entities based on cascade references, use the getCopy operation.
• Access permissions are enforced based on the provided token.
• The operation does not follow references to other entities; it only returns the requested entity.
• If you need to retrieve related entities, you'll need to make separate getById calls or use a query with includes.