Entity Service API

Introduction

The GSB Entity Service API provides a comprehensive set of operations for managing entity data and definitions within the GSB platform. It allows you to create, read, update, and delete entity data, as well as define and modify entity schemas.

Key Concepts

Entities

Entities represent business objects in your application domain. Each entity has:

• A unique identifier
• A set of properties (fields)
• Optional relationships with other entities
• Metadata describing its structure and behavior

Entity Definitions

Entity definitions (schemas) define the structure of entities:

• Property definitions (name, type, constraints)
• Relationships with other entity types
• Indexes for optimizing queries
• Validation rules
• Display and UI metadata

Properties

Properties are the individual fields that make up an entity:

• Simple types (string, number, boolean, date)
• Complex types (objects, arrays)
• References to other entities
• Computed properties

Authentication

The API uses token-based authentication. Most operations require a valid authentication token, which should be included in the request parameters. The token determines the permissions and access level for the operations.

Common Parameters

Most operations accept these common parameters:

Parameter	Type	Description
token	string	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	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 Format

All API operations return responses in a consistent format:

Success Response

{
    "success": true,
    "data": {
        // Operation-specific response data
    }
}

Error Response

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

Operation Categories

Entity Data Operations

Operations for working with entity data:

• getById: Retrieve an entity by its ID
• getCopy: Get a copy of an entity with a new ID
• query: Query entities based on filters
• queryMapped: Query entities with mapped results
• save: Create or update an entity
• saveMulti: Create or update multiple entities
• delete: Delete an entity by ID
• deleteQuery: Delete entities matching a query

Entity Relationship Operations

Operations for managing relationships between entities:

• saveMappedItems: Save relationships between entities
• removeMappedItems: Remove relationships between entities

Entity Definition Operations

Operations for managing entity definitions (schemas):

• getEntityDef: Get an entity definition by ID
• getDefinition: Get an entity definition by name
• queryEntityDefs: Query entity definitions
• createEntityDef: Create a new entity definition
• updateEntityDef: Update an existing entity definition
• getCommonPropertyDefs: Get common property definitions

Property Operations

Operations for managing entity properties:

• addProperty: Add a property to an entity definition
• updateProperty: Update a property in an entity definition
• removeProperty: Remove a property from an entity definition

Workflow Operations

Operations for executing workflows:

• runWorkflow: Execute a workflow
• startWorkflow: Start a workflow
• runWfFunction: Run a workflow function
• iterateTask: Iterate through a workflow task

Documentation Operations

Operations for retrieving API documentation:

• getDocs: Get comprehensive API documentation
• getApiDocs: Get general API information

Best Practices

1. Error Handling: Always check the success field in responses and handle errors appropriately.

2. Pagination: When querying large datasets, use pagination parameters to limit the result size.

3. Validation: Validate entity data against entity definitions before saving to avoid errors.

4. Transactions: For operations that modify multiple entities, consider using batch operations like saveMulti to ensure atomicity.

5. Security: Always use the principle of least privilege when assigning permissions to tokens.

6. Performance: Use appropriate indexes in entity definitions to optimize query performance.

7. Caching: Consider caching frequently accessed entity definitions and reference data.

Getting Started

To get started with the GSB Entity Service API:

1. Obtain an authentication token with appropriate permissions.

2. Explore the available entity definitions using queryEntityDefs.

3. Retrieve detailed documentation for specific operations using getDocs.

4. Start with simple operations like getById and query to retrieve data.

5. Progress to more complex operations as you become familiar with the API.

Additional Resources

• For detailed documentation on each operation, use the getDocs operation.
• For information about the API version and general metadata, use the getApiDocs operation.