Business API Design Specification - Delete Coursepack

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 deleteCoursePack 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 deleteCoursePack Business API is designed to handle a delete operation on the CoursePack data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow.

API Description

Tutor deletes their course pack. Only owner tutor or admin can delete. Tutors are blocked if active enrollments exist. Admin can force-delete with a reason, which triggers pro-rata refunds and student notifications.

API Frontend Description By The Backend Architect

Tutors cannot delete a course with active enrollments — they should unpublish instead. Admin can force-delete with a mandatory reason; this triggers automatic pro-rata refunds and email notifications to affected students.

API Options

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 deleteCoursePack Business API includes a REST controller that can be triggered via the following route:

/v1/coursepacks/:coursePackId

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.

MCP Tool

REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This deleteCoursePack Business API will be registered as a tool on the MCP server within the service binding.

API Parameters

The deleteCoursePack Business API has 2 parameters 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:

Regular Parameters

Name Type Required Default Location Data Path
coursePackId ID Yes - urlpath coursePackId
Description: This id paremeter is used to select the required data object that will be deleted
removalReason String No - body removalReason
Description: Required when admin deletes a course with active enrollments. Reason is sent to affected students via email.

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 deleteCoursePack 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 requires login (loginRequired = true). Requests from non-logged-in users will return a 401 Unauthorized error. Login is necessary but not sufficient, as additional role, permission, or other authorization checks may still apply.

Ownership Checks

Role and Permission Settings

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 a 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.

runMScript(() => ({$and:[{id:this.coursePackId},{isActive:true}]}), {"path":"services[1].businessLogic[6].whereClause.fullWhereClause"})

Delete Options

Use these options to set delete specific settings.

useSoftDelete: true If true, the record will be marked as deleted (isActive: false) instead of removed. The implementation depends on the data object’s soft delete configuration.

Business Logic Workflow

[1] Step : startBusinessApi

Manager initializes context, prepares request/session objects, and sets up 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

Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps.

You can use the following settings to change some behavior of this step. customParameters, redisParameters

[3] Step : transposeParameters

Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing.

[4] Step : checkParameters

Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails.

[5] Step : checkBasicAuth

Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions.

You can use the following settings to change some behavior of this step. authOptions

[6] Step : buildWhereClause

Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation.

You can use the following settings to change some behavior of this step. whereClause

[7] Step : fetchInstance

Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks.

[8] Action : checkActiveEnrollments

Action Type: FunctionCallAction

Check if this course pack has any active enrollments before allowing deletion

class Api {
  async checkActiveEnrollments() {
    try {
      return await runMScript(
        () =>
          (async () =>
            await LIB.checkCoursePackActiveEnrollments(this.coursePackId))(),
        {
          path: "services[1].businessLogic[6].actions.functionCallActions[0].callScript",
        },
      );
    } catch (err) {
      console.error("Error in FunctionCallAction checkActiveEnrollments:", err);
      throw err;
    }
  }
}

[9] Action : blockTutorDeleteWithEnrollments

Action Type: ValidationAction

Block tutors from deleting courses that have active enrollments. They should unpublish instead.

class Api {
  async blockTutorDeleteWithEnrollments() {
    const isValid = runMScript(
      () =>
        !(
          this.session.roleId === "tutor" &&
          this.enrollmentCheck &&
          this.enrollmentCheck.hasActiveEnrollments
        ),
      {
        path: "services[1].businessLogic[6].actions.validationActions[0].validationScript",
      },
    );

    if (!isValid) {
      throw new BadRequestError(
        "You cannot delete a course with active enrollments. Please unpublish the course instead so existing students can continue their lessons.",
      );
    }
    return isValid;
  }
}

[10] Action : requireReasonForAdminCascade

Action Type: ValidationAction

Admin must provide a removal reason when deleting a course with active enrollments

class Api {
  async requireReasonForAdminCascade() {
    const isValid = runMScript(
      () =>
        !(
          this.session.roleId === "admin" &&
          this.enrollmentCheck &&
          this.enrollmentCheck.hasActiveEnrollments &&
          (!this.removalReason || this.removalReason.trim().length === 0)
        ),
      {
        path: "services[1].businessLogic[6].actions.validationActions[1].validationScript",
      },
    );

    if (!isValid) {
      throw new BadRequestError(
        "A removal reason is required when deleting a course with active enrollments. This reason will be sent to affected students.",
      );
    }
    return isValid;
  }
}

[11] Action : triggerCascadeRefunds

Action Type: FunctionCallAction

Admin cascade: trigger pro-rata refunds for all active enrollments and notify students

class Api {
  async triggerCascadeRefunds() {
    try {
      return await runMScript(
        () =>
          (async () =>
            await LIB.triggerAdminCourseRemovalCascade(
              this.coursePackId,
              this.removalReason,
              this.enrollmentCheck,
              this.session,
            ))(),
        {
          path: "services[1].businessLogic[6].actions.functionCallActions[1].callScript",
        },
      );
    } catch (err) {
      console.error("Error in FunctionCallAction triggerCascadeRefunds:", err);
      throw err;
    }
  }
}

[12] Step : checkInstance

Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement.

[13] Step : mainDeleteOperation

Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration.

You can use the following settings to change some behavior of this step. deleteOptions

[14] Action : addCascadeInfo

Action Type: AddToResponseAction

class Api {
  async addCascadeInfo() {
    try {
      this.output["cascadeResult"] = runMScript(() => this.cascadeResult, {
        path: "services[1].businessLogic[6].actions.addToResponseActions[0].context[0].contextValue",
      });

      return true;
    } catch (error) {
      console.error("AddToResponseAction error:", error);
      throw error;
    }
  }
}

[15] Step : buildOutput

Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output.

[16] Step : sendResponse

Manager delivers the response to the client and finalizes any temporary internal structures.

[17] Step : raiseApiEvent

Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow.

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 deleteCoursePack api has got 2 regular client parameters

Parameter Type Required Population
coursePackId ID true request.params?.[“coursePackId”]
removalReason String request.body?.[“removalReason”]

REST Request

To access the api you can use the REST controller with the path DELETE /v1/coursepacks/:coursePackId

  axios({
    method: 'DELETE',
    url: `/v1/coursepacks/${coursePackId}`,
    data: {
            removalReason:"String",  
    
    },
    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 coursePack object in the respones. However, some properties may be omitted based on the object’s internal logic.

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "coursePack",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"coursePack": {
		"id": "ID",
		"tutorProfileId": "ID",
		"title": "String",
		"description": "Text",
		"price": "Double",
		"category": "String",
		"schedulingType": "Enum",
		"schedulingType_idx": "Integer",
		"minWeeklyClasses": "Integer",
		"preliminaryMeetingRequired": "Boolean",
		"isPublished": "Boolean",
		"maxDailyLessons": "Integer",
		"requiredClassesCount": "Integer",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"moderationNote": "String",
		"maxPeriodValue": "Integer",
		"maxPeriodUnit": "Enum",
		"maxPeriodUnit_idx": "Integer",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}