# Business API Design Specification - `Get Briefuser` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getBriefUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getBriefUser` Business API is designed to handle a `get` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used by public to get simple user profile information. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `briefuser-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getBriefUser` Business API includes a REST controller that can be triggered via the following route: `/v1/briefuser/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `getBriefUser` Business API includes a gRPC controller that can be triggered via the following function: `getBriefUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getBriefUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getBriefUser` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Regular Parameters | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getBriefUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API is **public** and can be accessed without login (`loginRequired = false`). --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause 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.", `id`,`fullname`,`avatar` ## Where Clause 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. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js runMScript(() => ({$and:[{id:this.userId},{isActive:true}]}), {"path":"services[0].businessLogic[11].whereClause.fullWhereClause"}) ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `sseSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getBriefUser` api has got 1 regular client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "isActive": true } } ```