Service

Business Api

Defines a Business API, a high-level abstraction representing a specific business operation on a primary data object within a Mindbricks Service.

MPO Version: 1.3.0

Defines a Business API, a high-level abstraction representing a specific business operation on a primary data object. It encapsulates intent (e.g., get, create, delete), parameters, trigger mechanisms, and a structured workflow composed of modular actions. Each Business API offers more expressive and decoupled control over behavior and access.

interface BusinessApi = {
  apiOptions : ApiOptions;
  authOptions : ApiAuthOptions;
  customParameters : BusinessApiParameter[];
  redisParameters : RedisApiParameter[];
  restSettings : ApiRestSettings;
  grpcSettings : ApiGrpcSettings;
  kafkaSettings : ApiKafkaSettings;
  socketSettings : ApiSocketSettings;
  cronSettings : ApiCronSettings;
  selectClause : SelectClauseSettings;
  dataClause : DataClauseSettings;
  whereClause : WhereClauseSettings;
  deleteOptions : DeleteOptions;
  getOptions : GetOptions;
  listOptions : ListOptions;
  paginationOptions : PaginationOptions;
  actions : BusinessApiActionStore;
  workflow : BusinessWorkflow;
}

Field	Description
apiOptions	Defines the name,type, dataObject and description of the business api as well as its basic options
authOptions	Defines core authentication and authorization settings for a Business API. These settings cover session validation, role and ownership checks, and access scope (e.g., tenant vs. SaaS-level). While these options are sufficient for most use cases, more fine-grained access control—such as conditional permissions or contextual ownership—should be implemented using explicit access control actions (e.g., `PermissionCheckAction`, `MembershipCheckAction`, `ObjectPermissionCheckAction`).
customParameters	An array of manually defined parameters that are extracted from the incoming request (e.g., body, query, session). These are configured using `BusinessApiParameter` and are written to the context as `this.<name>` before workflow execution begins.
redisParameters	An array of parameters fetched from Redis based on dynamically computed keys. These are defined using `RedisApiParameter` and are written to the context as `this.<name>`, just like custom parameters.
restSettings	Defines HTTP REST controller settings such as method and route path. Automatically generated using naming conventions, but can be customized for fine-grained control over REST behavior, parameter mapping, or URL design.
grpcSettings	Enables gRPC access for this Business API and configures the request and response schemas. gRPC is disabled by default unless explicitly configured.
kafkaSettings	Enables this Business API to be triggered by Kafka events. This controller listens for messages published to configured Kafka topics, allowing the API to respond to system-level events (e.g., file uploaded, user signed up) or external integrations. This is commonly used for decoupled orchestration between services or for reacting to events emitted by backend libraries and storage providers.
socketSettings	Enables invocation of this Business API over WebSocket channels. Useful for real-time communication where APIs must respond to push-based client interactions.
cronSettings	Schedules this Business API for automatic execution at specified intervals. Useful for background tasks, data cleanup, or scheduled jobs. Uses cron expressions to define timing.
selectClause	Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.
dataClause	Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.
whereClause	Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record.
deleteOptions	Contains settings specific to `delete` type APIs, such as soft-delete configurations or cascade options.
getOptions	Contains settings specific to `get` type APIs, such as instance enrichment, fallback behaviors, or object caching.
listOptions	Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records.
paginationOptions	Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion.
actions	Represents the available logic actions that can be referenced by the Business API's workflow. Actions include data fetches, validation, permission checks, interservice calls, transformations, and output shaping.
workflow	Defines the logical flow of the Business API, composed of sequenced action ids grouped by lifecycle stages. This workflow is generated visually in the architecture UI or programmatically inferred from the API's type.

ApiOptions

MPO Version: 1.3.0

Main configuration section for a Business API. This object includes essential attributes such as naming, access control, event handling, input generation, and fallback strategies. In many cases, configuring this section alone is sufficient to define the primary behavior an API entry point.

interface ApiOptions = {
  dataObjectName : LocalDataObjectName;
  crudType : CrudTypes;
  name : String;
  apiDescription : Text;
  frontendDocument : Text;
  raiseApiEvent : Boolean;
  raiseDbLevelEvents : Boolean;
  autoParams : Boolean;
  readFromEntityCache : Boolean;
}

Was this page helpful?

Built with Documentation.AI

Last updated today