# LinkedIn Clone - Frontend Development Prompts > AI-assisted frontend development prompts for LinkedIn Clone This document contains all frontend development prompts that can be used to build the user interface for this project. Each prompt provides detailed specifications for implementing specific frontend features. --- ## Table of Contents - [Introduction](#introduction) - [Project Introduction & Setup](#frontend-prompts-frontend-prompt-1-projectintroduction) - [Authentication Management](#frontend-prompts-frontend-prompt-2-authmanagement) - [Verification Management](#frontend-prompts-frontend-prompt-3-verification) - [Profile Management](#frontend-prompts-frontend-prompt-4-profile) - [User Management](#frontend-prompts-frontend-prompt-5-usermanagement) - [MCP BFF Integration](#frontend-prompts-frontend-prompt-6-mcpbffintegration) - [JobApplication Service](#frontend-prompts-frontend-prompt-7-jobapplicationservice) - [Networking Service](#frontend-prompts-frontend-prompt-8-networkingservice) - [Company Service](#frontend-prompts-frontend-prompt-9-companyservice) - [Content Service](#frontend-prompts-frontend-prompt-10-contentservice) - [Messaging Service](#frontend-prompts-frontend-prompt-11-messagingservice) - [Profile Service](#frontend-prompts-frontend-prompt-12-profileservice) - [Profile Service Premiumsubscription Payment Flow](#frontend-prompts-frontend-prompt-13-premiumsubscription-payment-flow) - [AgentHub Service](#frontend-prompts-frontend-prompt-14-agenthubservice) --- ## Introduction ### Project Overview # LinkedIn Clone Version : 1.0.2 This project's structure and ideas are the same as he real linkedIn webiste ## How to Use Project Documents The `Linkedin` project has been designed and generated using **Mindbricks**, a powerful microservice-based backend generation platform. All documentation is automatically produced by the **Mindbricks Genesis Engine**, based on the high-level architectural patterns defined by the user or inferred by AI. This documentation set is intended for both **AI agents** and **human developers**—including frontend and backend engineers—who need precise and structured information about how to interact with the backend services of this project. Each document reflects the live architecture of the system, providing a reliable reference for API consumption, data models, authentication flows, and business logic. By following this documentation, developers can seamlessly integrate with the backend, while AI agents can use it to reason about the service structure, make accurate decisions, or even generate compatible client-side code. ## Accessing Project Services Each service generated by Mindbricks is exposed via a **dedicated REST API** endpoint. Every service documentation set includes the **base URL** of that service along with the **specific API paths** for each available route. Before consuming any API, developers or agents must understand the service URL structure and environment-specific endpoints. ### Service Endpoint Structure | Environment | URL Pattern Example | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/auth-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/auth-api` | | **Production** | `https://linkedin.mindbricks.co/auth-api` | Replace `auth` with the actual service name as lower case (e.g., `order-api`, `bff-service`, customermanagement-api etc.). ### Environment Usage Notes * **Preview APIs** become accessible after a project is previewed inside the Mindbricks platform. These are ideal for development and testing. * **Staging** and **Production** APIs are only accessible after the project is deployed to cloud environments provisioned via Mindbricks. * In some cases, the project owner may choose to deploy services on their **own infrastructure**. In such scenarios, the service base URLs will be **custom** and should be communicated manually by the project owner to developers or AI agents. > **Frontend applications** should be designed to **easily switch between environments**, allowing dynamic endpoint targeting for Preview, Staging, and Production. ## Getting Started: Use the Auth Service First Before interacting with other services in the `Linkedin` project, **AI agents and developers should begin by integrating with the Auth Service**. Mindbricks automatically generates a dedicated authentication microservice based on the project’s authentication definitions provided by the architect. This service provides the essential user and access management foundation for the project. Agents should first utilize the Auth Service to: * Register and authenticate users (login) * Manage users, roles, and permissions * Handle user groups (if defined) * Support multi-tenancy logic (if configured) * Perform Policy-Based Access Control (PBAC), if activated by the architect ### Auth Service Documentation Use the following resources to understand and integrate the Auth Service: * **REST API Guide** – ideal for frontend and direct HTTP usage [Auth REST API Guide](/document/docs/auth-service/rest-api-guide.html) * **Event Guide** – helpful for event-driven or cross-service integrations [Auth Event Guide](/document/docs/auth-service/event-guide.html) * **Service Design Document** – overall structure, patterns, and logic [Auth Service Design](/document/docs/auth-service/service-design.html) > **Note:** For most frontend use cases, the **REST API Guide** will be the primary source. The **Event Guide** and **Service Design** documents are especially useful when integrating with other backend microservices or building systems that interact with the auth service indirectly. ## Using the BFF (Backend-for-Frontend) Service In Mindbricks, all backend services are designed with an advanced **CQRS (Command Query Responsibility Segregation)** architecture. Within this architecture, **business services** are responsible for managing their respective domains and ensuring the accuracy and freshness of domain data. The **BFF service** complements these business services by providing a **read-only** aggregation and query layer tailored specifically for frontend and client-side applications. ### Key Principles of the BFF Service * **Elasticsearch Replicas for Fast Queries:** Each data object managed by a business service is automatically replicated as an **Elasticsearch index**, making it accessible for fast, frontend-oriented queries through the BFF. * **Cross-Service Data Aggregation:** The BFF offers an **aggregation layer** capable of combining data across multiple services, enabling complex filters, searches, and unified views of related data. * **Read-Only by Design:** The BFF service is **strictly read-only**. All create, update, or delete operations must be performed through the relevant business services, or via event-driven sagas if designed. ### BFF Service Documentation * **REST API Guide** – querying aggregated and indexed data [BFF REST API Guide](/document/docs/bff-service/rest-api-guide.html) * **Event Guide** – syncing strategies across replicas [BFF Event Guide](/document/docs/bff-service/event-guide.html) * **Service Design** – aggregation patterns and index structures [BFF Service Design](/document/docs/bff-service/service-design.html) > **Tip:** Use the BFF service as the **main entry point for all frontend data queries**. It simplifies access, reduces round-trips, and ensures that data is shaped appropriately for the UI layer. ## Business Services Overview The `LinkedIn Clone` project consists of multiple **business services**, each responsible for managing a specific domain within the system. These services expose their own REST APIs and documentation sets, and are accessible based on the environment (Preview, Staging, Production). ### Usage Guidance Business services are primarily designed to: * Handle the **state and operations of domain data** * Offer **Create, Update, Delete** operations over owned entities * Serve **direct data queries** (`get`, `list`) for their own objects when needed For advanced query needs across multiple services or aggregated views, prefer using the [BFF service](#using-the-bff-backend-for-frontend-service). ### Available Business Services ### jobApplication Service **Description:** Microservice handling job postings (created by recruiters/company admins), job applications (created by users), allowing job search, application submission, and status update workflows. Enforces business rules around application status, admin controls, and lets professionals apply and track job applications .within the network. **Documentation:** * [REST API Guide](/document/docs/jobApplication-service/rest-api-guide.html) * [Event Guide](/document/docs/jobApplication-service/event-guide.html) * [Service Design](/document/docs/jobApplication-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/jobapplication-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/jobapplication-api` | | **Production** | `https://linkedin.mindbricks.co/jobapplication-api` | ### networking Service **Description:** Handles professional networking logic for user-to-user connections: manages connection requests, accepted relationships, listing/removal, permissions, and state transitions. Publishes connection lifecycle events for notification... **Documentation:** * [REST API Guide](/document/docs/networking-service/rest-api-guide.html) * [Event Guide](/document/docs/networking-service/event-guide.html) * [Service Design](/document/docs/networking-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/networking-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/networking-api` | | **Production** | `https://linkedin.mindbricks.co/networking-api` | ### company Service **Description:** Handles company profiles, company admin assignments, company following, and posting company updates/news. Enables professionals to follow companies, get updates, and enables admins to manage company presence.. **Documentation:** * [REST API Guide](/document/docs/company-service/rest-api-guide.html) * [Event Guide](/document/docs/company-service/event-guide.html) * [Service Design](/document/docs/company-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/company-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/company-api` | | **Production** | `https://linkedin.mindbricks.co/company-api` | ### content Service **Description:** Handles creation, editing, and deletion of user posts (with attachments and visibility), user post feed aggregation, and post engagement (likes, comments). All with post-level visibility control (public/private).. **Documentation:** * [REST API Guide](/document/docs/content-service/rest-api-guide.html) * [Event Guide](/document/docs/content-service/event-guide.html) * [Service Design](/document/docs/content-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/content-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/content-api` | | **Production** | `https://linkedin.mindbricks.co/content-api` | ### messaging Service **Description:** Handles direct, private 1:1 and group messaging between users, conversation management, and message history/storage.. **Documentation:** * [REST API Guide](/document/docs/messaging-service/rest-api-guide.html) * [Event Guide](/document/docs/messaging-service/event-guide.html) * [Service Design](/document/docs/messaging-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/messaging-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/messaging-api` | | **Production** | `https://linkedin.mindbricks.co/messaging-api` | ### profile Service **Description:** Handles user professional profiles, including experience, education, skills, languages, certifications, profile photo, and visibility controls. Enables recruiter search, elastic-style indexing, and profile editing, with all data linked to authenticated users.. **Documentation:** * [REST API Guide](/document/docs/profile-service/rest-api-guide.html) * [Event Guide](/document/docs/profile-service/event-guide.html) * [Service Design](/document/docs/profile-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/profile-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/profile-api` | | **Production** | `https://linkedin.mindbricks.co/profile-api` | ### agentHub Service **Description:** AI Agent Hub **Documentation:** * [REST API Guide](/document/docs/agentHub-service/rest-api-guide.html) * [Event Guide](/document/docs/agentHub-service/event-guide.html) * [Service Design](/document/docs/agentHub-service/service-design.html) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/agenthub-api` | | **Staging** | `https://linkedin-stage.mindbricks.co/agenthub-api` | | **Production** | `https://linkedin.mindbricks.co/agenthub-api` | ## Connect via MCP (Model Context Protocol) All backend services in the `Linkedin` project expose their Business APIs as **MCP tools**. These tools are aggregated by the **MCP-BFF** service into a single unified endpoint that external AI tools can connect to. ### Unified MCP Endpoint | Environment | StreamableHTTP (recommended) | SSE (legacy fallback) | |-------------|------------------------------|------------------------| | **Preview** | `https://linkedin.prw.mindbricks.com/mcpbff-api/mcp` | `https://linkedin.prw.mindbricks.com/mcpbff-api/mcp/sse` | | **Staging** | `https://linkedin-stage.mindbricks.co/mcpbff-api/mcp` | `https://linkedin-stage.mindbricks.co/mcpbff-api/mcp/sse` | | **Production** | `https://linkedin.mindbricks.co/mcpbff-api/mcp` | `https://linkedin.mindbricks.co/mcpbff-api/mcp/sse` | ### Authentication MCP connections require authentication via the `Authorization` header: - **API Key (recommended for AI agents):** `Authorization: Bearer sk_mbx_your_api_key_here` API keys are long-lived and don't expire like JWT tokens. Create one from the profile page. - **JWT Token:** `Authorization: Bearer {accessToken}` Use a valid access token obtained from the login API. > **OAuth is not supported** for MCP connections at this time. ### Connecting from Cursor Add the following to your project's `.cursor/mcp.json`: ```json { "mcpServers": { "linkedin": { "url": "https://linkedin.prw.mindbricks.com/mcpbff-api/mcp", "headers": { "Authorization": "Bearer sk_mbx_your_api_key_here" } } } } ``` ### Connecting from Claude Desktop Add to your Claude Desktop configuration (`claude_desktop_config.json`): ```json { "mcpServers": { "linkedin": { "url": "https://linkedin.prw.mindbricks.com/mcpbff-api/mcp", "headers": { "Authorization": "Bearer sk_mbx_your_api_key_here" } } } } ``` ### What's Available Once connected, the AI tool can discover and call all Business API tools from all services — CRUD operations, custom queries, file operations, and more. The MCP-BFF handles routing each tool call to the correct backend service and propagates your authentication context. --- ## Conclusion This documentation set provides a comprehensive guide for understanding and consuming the `LinkedIn Clone` backend, generated by the Mindbricks platform. It is structured to support both AI agents and human developers in navigating authentication, data access, service responsibilities, and system architecture. To summarize: * Start with the **Auth Service** to manage users, roles, sessions, and permissions. * Use the **BFF Service** for optimized, read-only data queries and cross-service aggregation. * Refer to the **Business Services** when you need to manage domain-specific data or perform direct CRUD operations. Each service offers a complete set of documentation—REST API guides, event interface definitions, and design insights—to help you integrate efficiently and confidently. Whether you are building a frontend application, configuring an automation agent, or simply exploring the architecture, this documentation is your primary reference for working with the backend of this project. > For environment-specific access, ensure you're using the correct base URLs (Preview, Staging, Production), and coordinate with the project owner for any custom deployments. --- ### How to Use These Prompts These prompts are designed to be used with AI coding assistants to help build frontend features. Each prompt includes: 1. **Feature Description** - What the feature does and its purpose 2. **Data Models** - The backend data structures to work with 3. **API Endpoints** - Available REST APIs for the feature 4. **UI Requirements** - Specific user interface requirements 5. **Implementation Guidelines** - Best practices and patterns to follow When using these prompts with an AI assistant: - Copy the relevant prompt section - Provide context about your frontend framework (React, Vue, Angular, etc.) - Reference the REST API documentation for endpoint details --- ## Frontend Development Prompts # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 1 - Project Introduction & Setup** This is the introductory document for the **linkedin** frontend project. It is designed for AI agents that will generate frontend code to consume the project's backend. Read it carefully — it describes the project scope, architecture, API conventions, and initial screens you must build before proceeding to the feature-specific prompts that follow. This prompt will help you set up the project infrastructure, create the initial layout, home page, navigation, and any dummy screens. The subsequent prompts will provide detailed API documentation for each feature area. ## Project Introduction This project's structure and ideas are the same as he real linkedIn webiste ## Project Services Overview The project has **1 auth service**, **1 notification service**, **1 BFF service**, and **7 business services**, plus other helper services such as bucket and realtime. Each service is a separate microservice application and listens for HTTP requests at different service URLs. | # | Service | Description | API Prefix | |---|---------|-------------|------------| | 1 | auth | Authentication and user management | `/auth-api` | | 2 | jobApplication | Microservice handling job postings (created by recruiters/company admins), job applications (created by users), allowing job search, application submission, and status update workflows. Enforces business rules around application status, admin controls, and lets professionals apply and track job applications .within the network. | `/jobApplication-api` | | 3 | networking | Handles professional networking logic for user-to-user connections: manages connection requests, accepted relationships, listing/removal, permissions, and state transitions. Publishes connection lifecycle events for notification... | `/networking-api` | | 4 | company | Handles company profiles, company admin assignments, company following, and posting company updates/news. Enables professionals to follow companies, get updates, and enables admins to manage company presence.. | `/company-api` | | 5 | content | Handles creation, editing, and deletion of user posts (with attachments and visibility), user post feed aggregation, and post engagement (likes, comments). All with post-level visibility control (public/private).. | `/content-api` | | 6 | messaging | Handles direct, private 1:1 and group messaging between users, conversation management, and message history/storage.. | `/messaging-api` | | 7 | profile | Handles user professional profiles, including experience, education, skills, languages, certifications, profile photo, and visibility controls. Enables recruiter search, elastic-style indexing, and profile editing, with all data linked to authenticated users.. | `/profile-api` | | 8 | agentHub | AI Agent Hub | `/agentHub-api` | Detailed API documentation for each service will be given in the following prompts. In this document, you will build the initial project structure, home pages, and navigation. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API's response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the Backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. The base URL of the application in each environment is as follows: * **Preview:** `https://linkedin.prw.mindbricks.com` * **Staging:** `https://linkedin-stage.mindbricks.co` * **Production:** `https://linkedin.mindbricks.co` For the auth service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/auth-api` * **Staging:** `https://linkedin-stage.mindbricks.co/auth-api` * **Production:** `https://linkedin.mindbricks.co/auth-api` For each other service, append `/{serviceName}-api` to the environment base URL. Any request that requires login must include a valid token in the Bearer authorization header. Please note that for each service in the project (which will be introduced in following prompts) will use a different address so it is a good practice to define a separate client for each service in the frontend application lib source. Not only the different base urls, some services even may need different access rules when shaping the request. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Home Page First build a home page which shows some static content about the application, and has got login and registration (if is public) buttons. The home page should be updated later according to the content that each service provides, as a frontend developer use best and common practices to reflect the service content to the home page. User may also give extra information for the home page content in addition to this prompt. Note that this page should include a deployment (environment) selection option to set the base URL. Set the default to `production`. After user logs in, page header should show the current login state as in modern web pages, logged in user fullname, avatar, email and with a logout link, make a fancy current user component. The home page may have different views before and after login. ## Initial Navigation Structure Build the initial navigation/sidebar with placeholder pages for each area of the application. These will be implemented in detail by the subsequent prompts: - Home / Landing - Login - Register - Verification - Profile - User Management (admin) - JobApplication Service Pages - Networking Service Pages - Company Service Pages - Content Service Pages - Messaging Service Pages - Profile Service Pages - AgentHub Service Pages Create these as placeholder/dummy pages with a title and "Coming soon" note. They will be filled in by the following prompts. ## What To Build Now With this prompt, build: 1. **Project infrastructure** — routing, layout, environment config, API client setup (one client per service) 2. **Home page** with environment selector, login/register buttons, project description 4. **Placeholder pages** for all navigation items listed above 5. **Common components** — header with user info, navigation sidebar/menu, layout wrapper Do **not** implement authentication flows, registration, or any service-specific features yet — those will be covered in the next prompts. ## Common Reminders 1. When the application starts, please ensure that the `baseUrl` is set to the production server URL, and that the environment selector dropdown has the **Production** option selected by default. 2. Note that any API call to the application backend is based on a service base URL. Auth APIs use `/auth-api` prefix, and each business service uses `/{serviceName}-api` prefix after the application's base URL. 3. The deployment environment selector will only be used in the home page. If any page is called directly bypassing the home page, the page will use the stored or default environment. --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 2 - Authentication Management** This document covers the authentication features of the **linkedin** project: registration, login, logout, and session management. The project introduction, API conventions, base URLs, home page, and multi-tenancy setup were covered in the previous introductory prompt — make sure those are implemented before proceeding. All auth APIs use the auth service base URL with the `/auth-api` prefix (e.g., `https://linkedin.mindbricks.co/auth-api`). ### FRONTEND_URL The `FRONTEND_URL` environment variable is automatically set on the auth service from the project's **frontendUrl** setting in Basic Project Settings. It contains the base URL of the frontend application for the current deployment environment (e.g., `http://localhost:5173` for dev, `https://myapp.com` for production). Defaults if not configured: | Environment | Default | |-------------|---------| | dev | `http://localhost:5173` | | test | `https://linkedin.prw.mindbricks.com` | | stage | `https://linkedin-stage.mindbricks.co` | | prod | `https://linkedin.mindbricks.co` | This variable is used by the auth service for: - **Social login redirects** — after OAuth processing, the auth service redirects to `FRONTEND_URL + /auth/callback` (the frontend must have a page at this route; see the Social Login prompt for details) - **Email notification links** — verification, password reset, and other links in emails point back to the frontend You can customize `FRONTEND_URL` per environment by configuring the `frontendUrl` field in your project's Basic Project Settings (e.g., when using a custom domain). ## Registration Management ### User Registration User registration is public in the application. Please create a simple and polished registration page that includes only the necessary fields of the registration API. Using the `registeruser` route of the auth API, send the required fields from your registration page. The `registerUser` API in the `auth` service is described with the request and response structure below. Note that since the `registerUser` API is a business API, it is versioned; call it with the given version like `/v1/registeruser`. ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.["avatar"] | | password | String | true | request.body?.["password"] | | fullname | String | true | request.body?.["fullname"] | | email | String | true | request.body?.["email"] | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, the frontend code should handle any verification requirements. Verification Management will be given in the next prompt. The registration response will include a `user` object in the root envelope; this object contains user information with an `id` field. ## Login Management ### Login Identifier Model The **primary login identifier** for this application is the **email address**. Users register and log in using their email and password. No mobile field is stored in the user data model. The login page should include an email input and a password input. ### Login Flow After successful registration and completing any required verifications, the user can log in. Please create a minimal, polished login page as described above. Note that this page should respect the deployment (environment) selection option made in the home page to set the base URL. If the user reaches this page directly skipping home page, the default `production` deployment will be used. The login API returns a created session. This session can be retrieved later with the access token using the `/currentuser` system route. Any request that requires login must include a valid token. When a user logs in successfully, the response JSON includes a JWT access token in the `accessToken` field. Under normal conditions, this token is also set as a cookie and consumed automatically. However, since AI coding agents' preview options may fail to use cookies, ensure that each request includes the access token in the Bearer authorization header. If the login fails due to verification requirements, the response JSON includes an `errCode`. If it is `EmailVerificationNeeded`, start the email verification flow; if it is `MobileVerificationNeeded`, start the mobile verification flow. After a successful login, you can access session (user) information at any time with the `/currentuser` API. On inner pages, show brief profile information (avatar, name, etc.) using the session information from this API. Note that the `currentuser` API returns a session object, so there is no `id` property; instead, the values for the user and session are exposed as `userId` and `sessionId`. The response combines user and session information. The login, logout, and currentuser APIs are as follows. They are system routes and are not versioned. ### `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). The `mobile` field is also accepted when the user has a mobile number on file. #### Example ```js axios.post("/login", { email: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "sessionId": "e81c7d2b-4e95-9b1e-842e-3fb9c8c1df38", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... "accessToken": "ey7....", "userBucketToken": "e56d...." } ``` > **Note on bucket tokens:** The `userBucketToken` is for the **external bucket service** (used for general file uploads like documents and product images). **User avatars do not use the external bucket service** — they are uploaded via database buckets (dbBuckets) built into the auth service using the regular `accessToken`. See the Profile or Bucket Management sections for dbBucket avatar upload details. ### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates the session (if it exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` ### `GET /currentuser` — Current Session **Purpose** Returns the currently authenticated user's session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). #### Request *No parameters.* #### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` #### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` Note that the `currentuser` API returns a session object, so there is no `id` property, instead, the values for the user and session are exposed as `userId` and `sessionId`. The response is a mix of user and session information. #### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. After you complete this step, please ensure you have not made the following common mistakes: 1. The `/currentuser` API returns a mix of session and user data. There is no `id` property —use `userId` and `sessionId`. 2. Note that any API call to the auth service should use the `/auth-api` prefix after the application's base URL. **After this prompt, the user may give you new instructions to update your output or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 3 - Verification Management** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project's backend. This document includes the verification processes for the autheitcation flow. Please read it carefully and implement all requirements described here. The project has 1 auth service, 1 notification service, 1 BFF service, and 7 business services, plus other helper services such as bucket and realtime. In this document you will be informed only about the auth service. Each service is a separate microservice application and listens for HTTP requests at different service URLs. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Accessing the backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. For the auth service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/auth-api` * **Staging:** `https://linkedin-stage.mindbricks.co/auth-api` * **Production:** `https://linkedin.mindbricks.co/auth-api` Any request that requires login must include a valid token in the Bearer authorization header. ## After User Registration Frontend should also be aware of verification after any login attempt. The login request may return a 401 or 403 with the error codes that indicates the verification needs. ```json { //... "errCode": "EmailVerificationNeeded", // or "errCode": "MobileVerificationNeeded", } ``` ## Email Verification In the registration response, check the `emailVerificationNeeded` property in the response root. If it is `true`, start the email verification flow. After the login process, if you receive an HTTP error and the response contains an `errCode` with the value `EmailVerificationNeeded`, start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user's email. The backend will send a secret code to the provided email address. **The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the `secretCode` property of the response.** 2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. **If the `secretCode` is sent to the frontend for testing, display it on the input page so the user can copy and paste it.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. 4. When the user submits the code, complete the email verification using the `complete` route of the backend (described below) with the user's email and the secret code. 5. After a successful email verification response, please check the response object to have the property 'mobileVerificationNeeded' as `true`, if so navigate to the mobile verification flow as described below. **If no mobile verification is needed then just navigate the login page.** Below are the `start` and `complete` routes for email verification. These are system routes and therefore are not versioned. #### `POST /verification-services/email-verification/start` **Purpose:** Starts email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User's email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid" } ``` > ⚠️ In production, `secretCode` is **not** returned — it is only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User's email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid" } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Mobile Verification > **Mobile numbers must be in E.164 format** (`+` followed by country code and subscriber number, e.g. `+905551234567`). Use the `PhoneInput` component for mobile number inputs on verification pages. In the registration response, check the `mobileVerificationNeeded` property in the response root. If it is `true`, start the mobile verification flow. After the login process, if you receive a 403 error and the response contains an `errCode` with the value `MobileVerificationNeeded`, start the mobile verification flow. 1. Call the mobile verification `start` route of the backend (described below) with the user's email. The backend will send a secret code to the user's mobile number. **If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the `secretCode` property.** 2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. **If the `secretCode` is returned for testing, display it on the input page for easy copy/paste.** 3. When the user submits the code, complete mobile verification using the `complete` route of the backend (described below) with the user's email and the secret code. 4. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index shown in the message with the one on the screen. 5. After a successful mobile verification response, navigate to the login page. **Verification Order** If both `emailVerificationNeeded` and `mobileVerificationNeeded` are `true`, handle both verification flows in order. First complete email verification, then mobile verification. Below are the `start` and `complete` routes for mobile verification. These are system routes and therefore are not versioned. #### `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User's email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid" } ``` > ⚠️ `secretCode` is returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- #### `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid" } ``` --- ## Resetting Password Users can reset their forgotten passwords without a login required, through email verification. To be able to start a password reset flow, users will click on the "Reset Password" link in the login page. Since there are two verification methods, by email or by mobile, for password reset, when the reset password link is clicked, frontend should ask user if they want to make the verification through email of mobile. According to the users selection the frontend shoudl start the related flow as explaned below step by step. ## Password Reset By Email Flow 1. Call the password reset by email verification `start` route of the backend (described below) with the user's email. The backend will send a secret code to the provided email address. **The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the `secretCode` property of the response.** 2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. **If the `secretCode` is sent to the frontend for testing, display it on the input page so the user can copy and paste it.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. 4. The input page should also include a double input area for the user to enter and confirm their new password. 5. When the user submits the code and the new password, complete the password reset by email using the `complete` route of the backend (described below) with the user's email , the secret code and new password. 6. After a successful verification response, navigate to the login page. Below are the `start` and `complete` routes for password reset by email verification. These are system routes and therefore are not versioned. #### POST `/verification-services/password-reset-by-email/start` **Purpose**: Starts the password reset process by generating and sending a secret verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-------------------------------------| | email | String | Yes | The email address of the user | ```json { "email": "user@example.com" } ``` **Success Response** Returns secret code details (only in development environment) and confirmation that the verification step has been started. ```json { "userId": "user-uuid", "email": "user@example.com", "codeIndex": 1, "secretCode": "123456", "timeStamp": 1765484354, "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z", "verificationType": "byLink", } ``` ⚠️ In production, the secret code is only sent via email and not exposed in the API response. **Error Responses** - `401 NotAuthenticated`: Email address not found or not associated with a user. - `403 Forbidden`: Sending a code too frequently (spam prevention). --- #### POST `/verification-services/password-reset-by-email/complete` **Purpose**: Completes the password reset process by validating the secret code and updating the user's password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|----------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via email | | password | String | Yes | The new password the user wants to set | ```json { "email": "user@example.com", "secretCode": "123456", "password": "newSecurePassword123" } ``` **Success Response** ```json { "userId": "user-uuid", "email": "user@example.com", "isVerified": true } ``` **Error Responses** - `403 Forbidden`: - Secret code mismatch - Secret code expired - No ongoing verification found --- ## Password Reset By Mobile Flow 1. Call the password reset by mobile verification `start` route of the backend (described below) with the user's email. The backend will send a secret code to the user's mobile number. **If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the `secretCode` property.** 2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. **If the `secretCode` is returned for testing, display it on the input page for easy copy/paste.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. Also display the half masked `mobile`number that comes in the response, to tell the user that their code is sent to this number. 4. The input page should also include a double input area for the user to enter and confirm their new password. 5. When the user submits the code, complete mobile verification using the `complete` route of the backend (described below) with the user's email and the secret code. 6. After a successful mobile verification response, navigate to the login page. Below are the `start` and `complete` routes for password reset by mobile verification. These are system routes and therefore are not versioned. #### POST `/verification-services/password-reset-by-mobile/start` **Purpose**: Initiates the mobile-based password reset by sending a verification code to the user's mobile. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------| | email | String | Yes | The email of the user that resets the password | ```json { "email": "user@user.com" } ``` ### Success Response Returns the verification context (code returned only in development): ```json { "status": "OK", "codeIndex": 1, timeStamp: 133241255, "mobile": "+905.....67", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z", verificationType: "byLink" } ``` ⚠️ In production, the `secretCode` is not included in the response and is only sent via SMS. ### Error Responses - **400 Bad Request**: Mobile already verified - **403 Forbidden**: Rate-limited (code already sent recently) - **404 Not Found**: User with provided mobile not found --- #### POST `/verification-services/password-reset-by-mobile/complete` **Purpose**: Finalizes the password reset process by validating the received verification code and updating the user's password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|-------------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via SMS | | password | String | Yes | The new password to assign | ```json { "email": "user@example.com", "secretCode": "123456", "password": "NewSecurePassword123!" } ``` ### Success Response ```json { "userId": "user-uuid", "isVerified": true } ``` --- ** Please dont forget to arrange the code to be able to navigate to the verification pages both after registrations and login attempts if verification is needed.** **After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 4 - Profile Management** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project's backend. This document includes information and api descriptions about building a **profile page** in the frontend using the auth service profile api calls. Avatar images are stored in the auth service's database buckets — no external bucket service is needed for avatars. The project has 1 auth service, 1 notification service, 1 BFF service, and 7 business services, plus other helper services such as bucket and realtime. In this document you will use the auth service (including its database bucket endpoints for avatar uploads). Each service is a separate microservice application and listens for HTTP requests at different service URLs. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Accessing the backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the register and login pages include a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. The base URL of the application in each environment is as follows: * **Preview:** `https://linkedin.prw.mindbricks.com` * **Staging:** `https://linkedin-stage.mindbricks.co` * **Production:** `https://linkedin.mindbricks.co` For the auth service, service urls are as follows: * **Preview:** `https://linkedin.prw.mindbricks.com/auth-api` * **Staging:** `https://linkedin-stage.mindbricks.co/auth-api` * **Production:** `https://linkedin.mindbricks.co/auth-api` For each other service, the service URL will be given in the service sections. Any request that requires login must include a valid token in the Bearer authorization header. ## Avatar Storage (Database Buckets) User avatars and tenant avatars are stored directly in the auth service database using **database buckets** (dbBuckets). This means avatar files are uploaded to and downloaded from the **auth service itself** — no external bucket service is needed. The auth service provides these avatar buckets: ### User Avatar Bucket **Upload:** `POST {authBaseUrl}/bucket/userAvatars/upload` **Download by ID:** `GET {authBaseUrl}/bucket/userAvatars/download/{fileId}` **Download by Key:** `GET {authBaseUrl}/bucket/userAvatars/download/key/{accessKey}` - **Read access:** Public (anyone can view avatars, no auth needed for download) - **Write access:** Authenticated (any logged-in user can upload their own avatar) - **Allowed types:** image/png, image/jpeg, image/webp, image/gif - **Max size:** 5 MB - **Access key:** Each uploaded file gets a 12-character random key for shareable links **Upload example (multipart/form-data):** ```js const formData = new FormData(); formData.append('file', croppedImageBlob, 'avatar.png'); const response = await fetch(`${authBaseUrl}/bucket/userAvatars/upload`, { method: 'POST', headers: { 'Authorization': `Bearer ${accessToken}`, }, body: formData, }); const result = await response.json(); // result.file.id — the file ID (use for download URL) // result.file.accessKey — 12-char key for public sharing // result.file.fileName, result.file.mimeType, result.file.fileSize ``` **After uploading, update the user's avatar field** with the download URL: ```js const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/${result.file.id}`; // OR use the access key for a shorter, shareable URL: const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/key/${result.file.accessKey}`; await updateProfile({ avatar: avatarUrl }); ``` **Displaying avatars:** Since read access is public, avatar URLs can be used directly in `` tags without any authentication token: ```jsx Avatar ``` ### Listing and Deleting Avatars The auth service also provides metadata APIs for each bucket (auto-generated): | API | Method | Path | Description | |-----|--------|------|-------------| | `getUserAvatarsFile` | GET | `/v1/userAvatarsFiles/:id` | Get file metadata (no binary) | | `listUserAvatarsFiles` | GET | `/v1/userAvatarsFiles` | List files with filtering | | `deleteUserAvatarsFile` | DELETE | `/v1/userAvatarsFiles/:id` | Delete file and its data | ## Profile Page Design a profile page to manage (view and edit) user information. The profile page should include an avatar upload component that uploads to the database bucket. On the profile page, you will need 4 business APIs: `getUser` , `updateProfile`, `updateUserPassword` and `archiveProfile`. Do not rely on the `/currentuser` response for profile data, because it contains session information. The most recent user data is in the user database and should be accessed via the `getUser` business API. The `updateProfile`, `updateUserPassword` and `archiveProfile` api can only be called by the users themselves. They are designed specific to the profile page. **Avatar upload workflow:** 1. User selects an image → crop with `react-easy-crop` (install it, do not implement your own) 2. Convert cropped area to a Blob 3. Upload to `POST {authBaseUrl}/bucket/userAvatars/upload` with the access token 4. Get back the file metadata (id, accessKey) 5. Construct the download URL: `{authBaseUrl}/bucket/userAvatars/download/key/{accessKey}` 6. Call `updateProfile({ avatar: downloadUrl })` to save it **Note that the user cannot change/update their `email` or `roleId`.** For password update you should make a separate block in the UI, so that user can enter old password, new password and confirm new password before calling the `updateUserPassword`. Here are the 3 auth APIs—`getUser` , `updateProfile` and `updateUserPassword`— as follows: You can access these APIs through the auth service base URL, `{appUrl}/auth-api`. ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```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": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | | fullname | String | false | request.body?.["fullname"] | | avatar | String | false | request.body?.["avatar"] | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | | oldPassword | String | true | request.body?.["oldPassword"] | | newPassword | String | true | request.body?.["newPassword"] | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Archiving A Profile A user may want to archive their profile. So the profile page should include an archive section for the users to archive their accounts. When an account is archived, it is marked as archived and an aarchiveDate is atteched to the profile. All user data is kept in the database for 1 month after user archived. If user tries to login or register with the same email, the account will be activated again. But if no login or register occures in 1 month after archiving, the profile and its related data will be deleted permanenetly. So in the profile page, 1. The arcihve options should be accepted after user writes a text like ("ARCHİVE MY ACCOUNT") to a confirmation dialog, so that frontend UX can ensure this is not an unconscious request. 2. The user should be warned about the process, that his account will be available for a restore for 1 month. The archive api, can only be called by the users themselves and its used as follows. ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` --- After you complete this step, please ensure you have not made the following common mistakes: 1. Avatar uploads go to the **auth service's database bucket** endpoints (`/bucket/userAvatars/upload`), not to an external bucket service. Use the same `accessToken` (Bearer header) for both auth APIs and avatar bucket uploads — no bucket-specific tokens are needed. 2. Note that any api call to the application backend is based on a service base url, in this prompt all auth apis (including avatar bucket endpoints) should be called by the auth service base url. 3. On the profile page, fetch the latest user data from the service using `getUser`. The `/currentuser` API is session-stored data; the latest data is in the database. 4. When you upload the avatar image on the profile page, use the returned download URL as the user's `avatar` property and update the user record when the Save button is clicked. **After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 5 - User Management** This document is the 2nd part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project's backend. This document provides extensive instruction for administrative user management. ## Service Access User management is handled through auth service again. Auth service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the auth service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/auth-api` * **Staging:** `https://linkedin-stage.mindbricks.co/auth-api` * **Production:** `https://linkedin.mindbricks.co/auth-api` Please note that any feature in this document is open to admins only. When the user logins, the response includes a roleId field. This roleId should one of these following admin roles. `superAdmin`, `admin`, ## Scope Auth service provides following feature for user management in linkedin application. These features are already handled in the previous part. 1. User Registration 2. User Authentication 3. Password Reset 3. Email (and/or) Mobile Verification 4. Profile Management These features will be handled in this part. - User Management - User Groups Management - Permission Manageemnt ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API's response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## User Management User management will be one of the main parts of the administrative manageemnts, so there will be a minimal but fancy `users` page in the admin dashboard. ### User Roles - `superadmin` : The first creator of the backend, the owner of the application, root user, has got an absolute authroization on all actions. It can not be assgined any other user. It can't be unassigned. Super admin user can not be deleted in any way. - `admin` : The role that can be assigned to any user by the super admin. This role includes most permissions that super admin have, but admins can't assign admin roles, can't unassign an admin role, can't delete other users who have admin role. In addition to these limitations, some critical actions in the business services may also be open to only super admin. - `user` : The standard role that is assgined to every user when first created or registered. This role doesnt have any privilages and can access to their own data or public data. The roles object is a hardcoded object in the generated code, and it contains the following roles: ```json { "superAdmin": "'superAdmin'", "admin": "'admin'", "user": "'user'" } ``` Each user may have only one role, and it is given in `/login` , `/currentuser` or `/users/:userId` response as follows ```json { // ... "roleId":"superAdmin", // ... } ``` ## Listing Users You can list users using the `listUsers` api. ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** **Filter Parameters** The `listUsers` api supports 3 optional filter parameters for filtering list results: **email** (`String`): A string value to represent the user's email. - Single (partial match, case-insensitive): `?email=` - Multiple: `?email=&email=` - Null: `?email=null` **fullname** (`String`): A string value to represent the fullname of the user - Single (partial match, case-insensitive): `?fullname=` - Multiple: `?fullname=&fullname=` - Null: `?fullname=null` **roleId** (`String`): A string value to represent the roleId of the user. - Single (partial match, case-insensitive): `?roleId=` - Multiple: `?roleId=&roleId=` - Null: `?roleId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { // Filter parameters (see Filter Parameters section above) // email: '' // Filter by email // fullname: '' // Filter by fullname // roleId: '' // Filter by roleId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Searching Users You may search users with their full names, emails. The search is done in elasticsearch index of the user table so a fast response is provided by the backend. You can send search request on each character update in the search box but start searching after 3 chars. The keyword parameter that is used in the business logic of the api, is read from the keyword query parameter. eg: `GET /v1/searchusers?keyword=Joe` When the user deletes the search keyword, use the `listUsers` api to get the full list again. ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.["keyword"] | **keyword** : **Filter Parameters** The `searchUsers` api supports 1 optional filter parameter for filtering list results: **roleId** (`String`): A string value to represent the roleId of the user. - Single (partial match, case-insensitive): `?roleId=` - Multiple: `?roleId=&roleId=` - Null: `?roleId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', // Filter parameters (see Filter Parameters section above) // roleId: '' // Filter by roleId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` #### Pagination When you list the users please use pagination. To be able to use pagination you should provide a `pageNumber` paramater in the query. The default row count for one page is 25, add an option for user to change it to 50 or 100. You can provide this value to the api through the `pageRowCount` parameter; `GET /users?pageNumber=1&pageRowCount=50` ## Creating Users The user management console in the admin dashboard should provide UX components for user creating by admins. When creating users, it should also be possible to upload user avatar. Note that when creating, updating users, admins can not set emailVerified as true, since it is a logical mechanism and should be verified only through verification processes. ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.["avatar"] | | email | String | true | request.body?.["email"] | | password | String | true | request.body?.["password"] | | fullname | String | true | request.body?.["fullname"] | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Avatar Upload Avatars are stored in the auth service's **database bucket** — no external bucket service needed. Upload the avatar image to the auth service's userAvatars bucket endpoint: `POST {authBaseUrl}/bucket/userAvatars/upload` Use the regular access token (Bearer header) for authentication — the same token used for all other API calls. The upload body is `multipart/form-data` with a `file` field. After upload, the response returns file metadata including `id` and `accessKey`. Construct a public download URL and save it in the user's `avatar` field: ```js const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/key/${result.file.accessKey}`; await updateUser(userId, { avatar: avatarUrl }); ``` Since the userAvatars bucket has public read access, avatar URLs work directly in `` tags without auth. Before the avatar upload, use the `react-easy-crop` lib for zoom, pan and crop. This component is also used in the profile page — reuse the existing code. ## Updating Users User update is possible by `updateUser`api. However since this update api is also called by teh user themselves it is lmited with name and avatar change (or any other user related property). For roleId and password updates seperate apis are used. So arrange the user update UI as to update the user info, as to set roleId and as to update password. ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | | fullname | String | false | request.body?.["fullname"] | | avatar | String | false | request.body?.["avatar"] | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` For role updates there are some rules. 1. Superadmin role can not be unassigned even by superadmin. 2. Admin roles can be assgined or unassgined only by superadmin. 3. All other roles can be assigned and unassgined by admins and superadmin. For password updates there are some rules. 1. Superadmin and admin passwords can be updated only by superadmin. 2. Admins can update only non-admin passwords. ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | | roleId | String | true | request.body?.["roleId"] | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | | password | String | true | request.body?.["password"] | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Deleting Users Deleting users is possible in certain conditions. 1. SuperAdmin can not be deleted. 2. Admins can be deleted by only superadmin. 3. Users can be deleted by admins or superadmin. ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` --- When you list user group members, a `user` object will also be inserted in each userGroupMember object, with fullname, avatar, email. ## Avatar Storage (Database Buckets) (This information is also covered in the Profile prompt.) Avatars are stored in the auth service's **database buckets** — uploaded to and downloaded from the auth service directly using the regular access token. **User Avatar Bucket:** - Upload: `POST {authBaseUrl}/bucket/userAvatars/upload` (multipart/form-data, `file` field) - Download: `GET {authBaseUrl}/bucket/userAvatars/download/key/{accessKey}` (public, no auth needed) - Allowed: image/png, image/jpeg, image/webp, image/gif (max 5 MB) When uploading an avatar (for user creation or update), send the image to the bucket, get back the `accessKey`, construct the download URL, and store it in the user's `avatar` field via the update API. **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 6 - MCP BFF Integration** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project's backend. This document provides comprehensive instructions for integrating the **MCP BFF** (Model Context Protocol - Backend for Frontend) service into the frontend application. The MCP BFF is the central gateway between the frontend AI chat and all backend services. --- ## MCP BFF Architecture Overview The Linkedin application uses an **MCP BFF** service that aggregates multiple backend MCP servers into a single frontend-facing API. Instead of the frontend connecting to each service's MCP endpoint directly, it communicates exclusively through the MCP BFF. ``` ┌────────────┐ ┌───────────┐ ┌─────────────────┐ │ Frontend │────▶│ MCP BFF │────▶│ Auth Service │ │ (Chat UI) │ │ :3005 │────▶│ Business Svc 1 │ │ │◀────│ │────▶│ Business Svc N │ └────────────┘ SSE └───────────┘ └─────────────────┘ ``` ### Key Responsibilities - **Tool Aggregation**: Discovers and registers tools from all connected MCP services - **Session Forwarding**: Injects the user's `accessToken` into every MCP tool call - **AI Orchestration**: Routes user messages to the AI model, which decides which tools to call - **SSE Streaming**: Streams chat responses, tool executions, and results to the frontend in real-time - **Elasticsearch**: Provides direct search/aggregation endpoints across all project indices - **Logging**: Provides log viewing and real-time console streaming endpoints ## MCP BFF Service URLs For the MCP BFF service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/mcpbff-api` * **Staging:** `https://linkedin-stage.mindbricks.co/mcpbff-api` * **Production:** `https://linkedin.mindbricks.co/mcpbff-api` All endpoints below are relative to the MCP BFF base URL. --- ## Authentication All MCP BFF endpoints require authentication. The user's access token (obtained from the Auth service login) must be included in every request: ```js const headers = { 'Content-Type': 'application/json', 'Authorization': `Bearer ${accessToken}`, }; ``` --- ## Chat API (AI Interaction) The chat API is the primary interface for AI-powered conversations. It supports both regular HTTP responses and **SSE streaming** for real-time output. ### POST /api/chat — Regular Chat Send a message and receive the complete AI response. ```js const response = await fetch(`${mcpBffUrl}/api/chat`, { method: 'POST', headers, body: JSON.stringify({ message: "Show me all orders from last week", conversationId: "optional-conversation-id", // for conversation context context: {} // additional context }), }); ``` ### POST /api/chat/stream — SSE Streaming Chat (Recommended) Stream the AI response in real-time using Server-Sent Events (SSE). This is the recommended approach for chat UIs as it provides immediate feedback while the AI is thinking, calling tools, and generating text. **Request:** ```js const response = await fetch(`${mcpBffUrl}/api/chat/stream`, { method: 'POST', headers, body: JSON.stringify({ message: "Create a new product called Widget", conversationId: conversationId, // optional, auto-generated if omitted disabledServices: [], // optional, service names to exclude }), }); ``` **Response:** The server responds with `Content-Type: text/event-stream`. Each SSE frame follows the standard format: ``` event: \n data: \n \n ``` ### SSE Event Types The streaming endpoint emits the following event types in order: | Event | When | Data Shape | |-------|------|------------| | `start` | First event, once per stream | `{ conversationId, provider, aliasMapSummary }` | | `text` | AI text token streamed (many per response) | `{ content }` | | `tool_start` | AI decided to call a tool | `{ tool }` | | `tool_executing` | Tool invocation started with resolved args | `{ tool, args }` | | `tool_result` | Tool execution completed | `{ tool, result, success, error? }` — **check for `__frontendAction`** | | `error` | Unrecoverable error | `{ message }` | | `done` | Last event, once per stream | `{ conversationId, toolCalls, processingTime, aliasMapSummary }` | ### SSE Event Data Reference **`start`** — Always the first event. Use `conversationId` for subsequent requests in the same conversation. ```json { "conversationId": "1d143df6-29fd-49f6-823b-524b8b3b4453", "provider": "anthropic", "aliasMapSummary": { "enabled": true, "count": 0, "samples": [] } } ``` **`text`** — Streamed token-by-token as the AI generates its response. Concatenate `content` fields to build the full markdown message. ```json { "content": "Here" } { "content": "'s your" } { "content": " current session info" } ``` **`tool_start`** — The AI decided to call a tool. Use this to show a loading/spinner UI for the tool. ```json { "tool": "currentuser" } ``` **`tool_executing`** — Tool is now executing with these arguments. Use this to display what the tool is doing. ```json { "tool": "currentuser", "args": { "organizationCodename": "babil" } } ``` **`tool_result`** — Tool finished. Check `success` to determine if it succeeded. The `result` field contains the MCP tool response envelope. ```json { "tool": "currentuser", "result": { "success": true, "service": "auth", "tool": "currentuser", "result": { "content": [{ "type": "text", "text": "{...JSON...}" }] } }, "success": true } ``` On failure, `success` is `false` and an `error` string is present: ```json { "tool": "listProducts", "error": "Connection refused", "success": false } ``` **`done`** — Always the last event. Contains a summary of all tool calls made and total processing time in milliseconds. ```json { "conversationId": "1d143df6-29fd-49f6-823b-524b8b3b4453", "toolCalls": [ { "tool": "currentuser", "result": { "success": true, "..." : "..." } } ], "processingTime": 10026, "aliasMapSummary": { "enabled": true, "count": 6, "samples": [{ "alias": "user_admin_admin_com" }, { "alias": "tenant_admin_admin_com" }] } } ``` **`error`** — Sent when an unrecoverable error occurs (e.g., AI service unavailable). The stream ends after this event. ```json { "message": "AI service not configured. Please configure OPENAI_API_KEY or ANTHROPIC_API_KEY in environment variables" } ``` ### SSE Event Lifecycle A typical conversation stream follows this lifecycle: ``` start ├── text (repeated) ← AI's initial text tokens ├── tool_start ← AI decides to call a tool ├── tool_executing ← tool running with resolved args ├── tool_result ← tool finished ├── text (repeated) ← AI continues writing after tool result ├── tool_start → tool_executing → tool_result ← may repeat ├── text (repeated) ← AI's final text tokens done ``` Multiple tool calls can happen in a single stream. The AI interleaves text and tool calls — text before tools (explanation), tools in the middle (data retrieval), and text after tools (formatted response using the tool results). ### Inline Segment Rendering (Critical UX Pattern) **Tool cards MUST be rendered inline inside the assistant message bubble, at the exact position where they occur in the stream — not grouped at the top, not grouped at the bottom, and not outside the bubble.** The assistant message is an ordered list of **segments**: text segments and tool segments, interleaved in the order they arrive. Each segment appears inside the same message bubble, in sequence: ``` ┌─────────────────────────────────────────────────┐ │ [Rendered Markdown — text before tool call] │ │ │ │ ┌─ Tool Card ─────────────────────────────────┐ │ │ │ 🔧 currentuser ✓ success │ │ │ │ args: { organizationCodename: "babil" } │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ [Rendered Markdown — text after tool call] │ │ │ │ ┌─ Tool Card ─────────────────────────────────┐ │ │ │ 🔧 listProducts ✓ success │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ [Rendered Markdown — final text] │ └─────────────────────────────────────────────────┘ ``` To achieve this, maintain an **ordered segments array**. Each segment is either `{ type: 'text', content: string }` or `{ type: 'tool', ... }`. When SSE events arrive: 1. **`text`** — Append to the last segment if it is a text segment; otherwise push a new text segment. 2. **`tool_start`** — Push a new tool segment (status: `running`). This "cuts" the current text segment — any further `text` events after the tool completes will start a new text segment. 3. **`tool_executing`** — Update the current tool segment with `args`. 4. **`tool_result`** — Update the current tool segment with `result`, `success`, `error`. Check for `__frontendAction`. 5. After `tool_result`, the next `text` event creates a **new** text segment (the AI is now responding after reviewing the tool result). Render the message bubble by mapping over the segments array in order, rendering each text segment as markdown and each tool segment as a collapsible tool card. ### Parsing SSE Events (Frontend Implementation) Use the `fetch` API with a streaming reader. SSE frames can arrive split across chunks, so buffer partial lines: ```js async function streamChat(mcpBffUrl, headers, message, conversationId, onEvent) { const response = await fetch(`${mcpBffUrl}/api/chat/stream`, { method: 'POST', headers, body: JSON.stringify({ message, conversationId }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split('\n\n'); buffer = parts.pop(); // keep incomplete frame in buffer for (const part of parts) { let eventType = 'message'; let dataStr = ''; for (const line of part.split('\n')) { if (line.startsWith('event: ')) { eventType = line.slice(7).trim(); } else if (line.startsWith('data: ')) { dataStr += line.slice(6); } } if (dataStr) { try { const data = JSON.parse(dataStr); onEvent(eventType, data); } catch (e) { console.warn('Failed to parse SSE data:', dataStr); } } } } } ``` ### Building the Segments Array (React Example) ```js // segments: Array<{ type: 'text', content: string } | { type: 'tool', tool, args?, result?, success?, error?, status }> let segments = []; streamChat(mcpBffUrl, headers, userMessage, conversationId, (event, data) => { switch (event) { case 'start': conversationId = data.conversationId; segments = []; break; case 'text': { const last = segments[segments.length - 1]; if (last && last.type === 'text') { last.content += data.content; // append to current text segment } else { segments.push({ type: 'text', content: data.content }); // new text segment } rerenderBubble(segments); break; } case 'tool_start': // push a new tool segment — this "cuts" the text flow segments.push({ type: 'tool', tool: data.tool, status: 'running' }); rerenderBubble(segments); break; case 'tool_executing': { const toolSeg = findLastToolSegment(segments, data.tool); if (toolSeg) toolSeg.args = data.args; rerenderBubble(segments); break; } case 'tool_result': { const toolSeg = findLastToolSegment(segments, data.tool); if (toolSeg) { toolSeg.status = data.success ? 'complete' : 'error'; toolSeg.result = data.result; toolSeg.error = data.error; toolSeg.success = data.success; // Check for frontend action (QR code, data view, payment, secret) toolSeg.frontendAction = extractFrontendAction(data.result); } rerenderBubble(segments); break; } case 'error': segments.push({ type: 'text', content: `**Error:** ${data.message}` }); rerenderBubble(segments); break; case 'done': // Store final metadata (processingTime, aliasMapSummary) for the message finalizeMessage(segments, data); break; } }); function findLastToolSegment(segments, toolName) { for (let i = segments.length - 1; i >= 0; i--) { if (segments[i].type === 'tool' && segments[i].tool === toolName) return segments[i]; } return null; } ``` ### Rendering the Message Bubble Render each segment in order inside a single assistant message bubble: ```jsx function AssistantMessageBubble({ segments }) { return (
{segments.map((segment, i) => { if (segment.type === 'text') { return ; } if (segment.type === 'tool') { if (segment.frontendAction) { return ; } return ; } return null; })}
); } function ToolCard({ segment }) { const isRunning = segment.status === 'running'; const isError = segment.status === 'error'; return (
{isRunning && } {segment.tool} {!isRunning && (isError ? : )}
{segment.args && ( 
{JSON.stringify(segment.args, null, 2)}
 )} {segment.result && ( 
{JSON.stringify(segment.result, null, 2)}
 )} {segment.error &&
{segment.error}
}
); } ``` The tool card should be compact by default (just tool name + status icon) with collapsible sections for args and result, so it doesn't dominate the reading flow. While a tool is running (`status: 'running'`), show a spinner. When complete, show a check or error icon. ### Handling `__frontendAction` in Tool Results When the AI calls certain tools (e.g., QR code, data view, payment, secret reveal), the tool result contains a `__frontendAction` object. This signals the frontend to render a special UI component **inline in the bubble at the tool segment's position** instead of the default collapsible ToolCard. This is already handled in the segments code above — when `segment.frontendAction` is present, render an `ActionCard` instead of a `ToolCard`. The `extractFrontendAction` helper unwraps the action from various MCP response formats: ```js function extractFrontendAction(result) { if (!result) return null; if (result.__frontendAction) return result.__frontendAction; // Unwrap MCP wrapper format: result → result.result → content[].text → JSON let data = result; if (result?.result?.content) data = result.result; if (data?.content && Array.isArray(data.content)) { const textContent = data.content.find(c => c.type === 'text'); if (textContent?.text) { try { const parsed = JSON.parse(textContent.text); if (parsed?.__frontendAction) return parsed.__frontendAction; } catch { /* not JSON */ } } } return null; } ``` ### Frontend Action Types | Action Type | Component | Description | |-------------|-----------|-------------| | `qrcode` | `QrCodeActionCard` | Renders any string value as a QR code card | | `dataView` | `DataViewActionCard` | Fetches a Business API route and renders a grid or gallery | | `payment` | `PaymentActionCard` | "Pay Now" button that opens Stripe checkout modal | #### QR Code Action (`type: "qrcode"`) Triggered by the `showQrCode` MCP tool. Renders a QR code card from any string value. ```json { "__frontendAction": { "type": "qrcode", "value": "https://example.com/invite/ABC123", "title": "Invite Link", "subtitle": "Scan to open" } } ``` #### Data View Action (`type: "dataView"`) Triggered by `showBusinessApiListInFrontEnd` or `showBusinessApiGalleryInFrontEnd`. Frontend calls the provided Business API route using the user's bearer token, then renders: - `viewType: "grid"` as tabular rows/columns - `viewType: "gallery"` as image-first cards ```json { "__frontendAction": { "type": "dataView", "viewType": "grid", "title": "Recent Orders", "serviceName": "commerce", "apiName": "listOrders", "routePath": "/v1/listorders", "httpMethod": "GET", "queryParams": { "pageNo": 1, "pageRowCount": 10 }, "columns": [ { "field": "id", "label": "Order ID" }, { "field": "orderAmount", "label": "Amount", "format": "currency" } ] } } ``` #### Payment Action (`type: "payment"`) Triggered by the `initiatePayment` MCP tool. Renders a payment card with amount and a "Pay Now" button. ```json { "__frontendAction": { "type": "payment", "orderId": "uuid", "orderType": "order", "serviceName": "commerce", "amount": 99.99, "currency": "USD", "description": "Order #abc123" } } ``` ### Conversation Management ```js // List user's conversations GET /api/chat/conversations // Get conversation history GET /api/chat/conversations/:conversationId // Delete a conversation DELETE /api/chat/conversations/:conversationId ``` --- ## MCP Tool Discovery & Direct Invocation The MCP BFF exposes endpoints for discovering and directly calling MCP tools (useful for debugging or building custom UIs). ### GET /api/tools — List All Tools ```js const response = await fetch(`${mcpBffUrl}/api/tools`, { headers }); const { tools, count } = await response.json(); // tools: [{ name, description, inputSchema, service }, ...] ``` ### GET /api/tools/service/:serviceName — List Service Tools ```js const response = await fetch(`${mcpBffUrl}/api/tools/service/commerce`, { headers }); const { tools } = await response.json(); ``` ### POST /api/tools/call — Call a Tool Directly ```js const response = await fetch(`${mcpBffUrl}/api/tools/call`, { method: 'POST', headers, body: JSON.stringify({ toolName: "listProducts", args: { page: 1, limit: 10 }, }), }); const result = await response.json(); ``` ### GET /api/tools/status — Connection Status ```js const status = await fetch(`${mcpBffUrl}/api/tools/status`, { headers }); // Returns health of each MCP service connection ``` ### POST /api/tools/refresh — Reconnect Services ```js await fetch(`${mcpBffUrl}/api/tools/refresh`, { method: 'POST', headers }); // Reconnects to all MCP services and refreshes the tool registry ``` --- ## Elasticsearch API The MCP BFF provides direct access to Elasticsearch for searching, filtering, and aggregating data across all project indices. All Elasticsearch endpoints are under `/api/elastic`. ### GET /api/elastic/allIndices — List Project Indices Returns all Elasticsearch indices belonging to this project (prefixed with `linkedin_`). ```js const indices = await fetch(`${mcpBffUrl}/api/elastic/allIndices`, { headers }); // ["linkedin_products", "linkedin_orders", ...] ``` ### POST /api/elastic/:indexName/rawsearch — Raw Elasticsearch Query Execute a raw Elasticsearch query on a specific index. ```js const response = await fetch(`${mcpBffUrl}/api/elastic/products/rawsearch`, { method: 'POST', headers, body: JSON.stringify({ query: { bool: { must: [ { match: { status: "active" } }, { range: { price: { gte: 10, lte: 100 } } } ] } }, size: 20, from: 0, sort: [{ createdAt: "desc" }] }), }); const { total, hits, aggregations, took } = await response.json(); // hits: [{ _id, _index, _score, _source: { ...document... } }, ...] ``` Note: The index name is automatically prefixed with `linkedin_` if not already prefixed. ### POST /api/elastic/:indexName/search — Simplified Search A higher-level search API with built-in support for filters, sorting, and pagination. ```js const response = await fetch(`${mcpBffUrl}/api/elastic/products/search`, { method: 'POST', headers, body: JSON.stringify({ search: "wireless headphones", // Full-text search filters: { status: "active" }, // Field filters sort: { field: "createdAt", order: "desc" }, page: 1, limit: 25, }), }); ``` ### POST /api/elastic/:indexName/aggregate — Aggregations Run aggregation queries for analytics and dashboards. ```js const response = await fetch(`${mcpBffUrl}/api/elastic/orders/aggregate`, { method: 'POST', headers, body: JSON.stringify({ aggs: { status_counts: { terms: { field: "status.keyword" } }, total_revenue: { sum: { field: "amount" } }, monthly_orders: { date_histogram: { field: "createdAt", calendar_interval: "month" } } }, query: { range: { createdAt: { gte: "now-1y" } } } }), }); ``` ### GET /api/elastic/:indexName/mapping — Index Mapping Get the field mapping for an index (useful for building dynamic filter UIs). ```js const mapping = await fetch(`${mcpBffUrl}/api/elastic/products/mapping`, { headers }); ``` ### POST /api/elastic/:indexName/ai-search — AI-Assisted Search Uses the configured AI model to convert a natural-language query into an Elasticsearch query. ```js const response = await fetch(`${mcpBffUrl}/api/elastic/orders/ai-search`, { method: 'POST', headers, body: JSON.stringify({ query: "orders over $100 from last month that are still pending", }), }); // Returns: { total, hits, generatedQuery, ... } ``` --- ## Log API The MCP BFF provides log viewing endpoints for monitoring application behavior. ### GET /api/logs — Query Logs ```js const response = await fetch(`${mcpBffUrl}/api/logs?page=1&limit=50&logType=2&service=commerce&search=payment`, { headers, }); ``` **Query Parameters:** - `page` — Page number (default: 1) - `limit` — Items per page (default: 50) - `logType` — 0=INFO, 1=WARNING, 2=ERROR - `service` — Filter by service name - `search` — Search in subject and message - `from` / `to` — Date range (ISO strings) - `requestId` — Filter by request ID ### GET /api/logs/stream — Real-time Console Stream (SSE) Streams real-time console output from all services via Server-Sent Events. ```js const eventSource = new EventSource(`${mcpBffUrl}/api/logs/stream?services=commerce,auth`, { headers: { 'Authorization': `Bearer ${accessToken}` }, }); eventSource.addEventListener('log', (event) => { const logEntry = JSON.parse(event.data); // { service, timestamp, level, message, ... } }); ``` --- ## Available Services The MCP BFF connects to the following backend services: | Service | Description | |---------|-------------| | `auth` | Authentication, user management, sessions | | `jobApplication` | Microservice handling job postings (created by recruiters/company admins), job applications (created by users), allowing job search, application submission, and status update workflows. Enforces business rules around application status, admin controls, and lets professionals apply and track job applications .within the network. | | `networking` | Handles professional networking logic for user-to-user connections: manages connection requests, accepted relationships, listing/removal, permissions, and state transitions. Publishes connection lifecycle events for notification... | | `company` | Handles company profiles, company admin assignments, company following, and posting company updates/news. Enables professionals to follow companies, get updates, and enables admins to manage company presence.. | | `content` | Handles creation, editing, and deletion of user posts (with attachments and visibility), user post feed aggregation, and post engagement (likes, comments). All with post-level visibility control (public/private).. | | `messaging` | Handles direct, private 1:1 and group messaging between users, conversation management, and message history/storage.. | | `profile` | Handles user professional profiles, including experience, education, skills, languages, certifications, profile photo, and visibility controls. Enables recruiter search, elastic-style indexing, and profile editing, with all data linked to authenticated users.. | | `agentHub` | AI Agent Hub | Each service exposes MCP tools that the AI can call through the BFF. Use `GET /api/tools` to discover all available tools at runtime, or `GET /api/tools/service/:serviceName` to list tools for a specific service. --- ## MCP as Internal API Gateway The MCP-BFF service can also be used by the frontend as an **internal API gateway** for tool-based interactions. This is separate from external AI tool connections — it is meant for frontend code that needs to call backend tools programmatically. ### Direct Tool Calls (REST) Use the REST tool invocation endpoints for programmatic access from frontend code: ```js // List all available tools const tools = await fetch(`${mcpBffUrl}/api/tools`, { headers }); // Call a specific tool directly const result = await fetch(`${mcpBffUrl}/api/tools/call`, { method: 'POST', headers, body: JSON.stringify({ toolName: 'listProducts', args: { page: 1, limit: 10 }, }), }); ``` ### AI-Orchestrated Calls (Chat API) For AI-driven interactions, use the chat streaming API documented above (`POST /api/chat/stream`). The AI model decides which tools to call based on the user's message. Both approaches use the user's JWT access token for authentication — the MCP-BFF forwards it to the correct backend service. --- ## MCP Connection Info for Profile Page The user's **profile page** should include an informational section explaining how to connect external AI tools (Cursor, Claude Desktop, Lovable, Windsurf, etc.) to this application's backend via MCP. ### What to Display The MCP-BFF exposes a **unified MCP endpoint** that aggregates tools from all backend services into a single connection point: | Environment | URL | |-------------|-----| | **Preview** | `https://linkedin.prw.mindbricks.com/mcpbff-api/mcp` | | **Staging** | `https://linkedin-stage.mindbricks.co/mcpbff-api/mcp` | | **Production** | `https://linkedin.mindbricks.co/mcpbff-api/mcp` | For legacy MCP clients that don't support StreamableHTTP, an SSE fallback is available at the same URL with `/sse` appended (e.g., `.../mcpbff-api/mcp/sse`). ### Profile Page UI Requirements Add an **"MCP Connection"** or **"Connect External AI Tools"** card/section to the profile page with: 1. **Endpoint URL** — Display the MCP endpoint URL for the current environment with a copy-to-clipboard button. 2. **Ready-to-Copy Configs** — Show copy-to-clipboard config snippets for popular tools: **Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "linkedin": { "url": "https://linkedin.prw.mindbricks.com/mcpbff-api/mcp", "headers": { "Authorization": "Bearer your_access_token_here" } } } } ``` **Claude Desktop** (`claude_desktop_config.json`): ```json { "mcpServers": { "linkedin": { "url": "https://linkedin.prw.mindbricks.com/mcpbff-api/mcp", "headers": { "Authorization": "Bearer your_access_token_here" } } } } ``` 3. **Auth Note** — Note that users should replace `your_access_token_here` with a valid JWT access token from the login API. 4. **OAuth Note** — Display a note that OAuth authentication is not currently supported for MCP connections. 5. **Available Tools** — Optionally show a summary of available tool categories (e.g., "CRUD operations for all data objects, custom business APIs, file operations") or link to the tools discovery endpoint (`GET /api/tools`). --- **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 7 - JobApplication Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of jobApplication ## Service Access JobApplication service management is handled through service specific base urls. JobApplication service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the jobApplication service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/jobapplication-api` * **Staging:** `https://linkedin-stage.mindbricks.co/jobapplication-api` * **Production:** `https://linkedin.mindbricks.co/jobapplication-api` ## Scope **JobApplication Service Description** Microservice handling job postings (created by recruiters/company admins), job applications (created by users), allowing job search, application submission, and status update workflows. Enforces business rules around application status, admin controls, and lets professionals apply and track job applications .within the network. JobApplication service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`jobPosting` Data Object**: Job posting entity representing an open position with a company. Created/managed by company admins or recruiters. Fields include companyId, postedByUserId, title, details, requirements, employment type, salary, deadline, etc. **`jobApplication` Data Object**: Record of a user applying for a specific jobPosting (tracks application/resume/status/audit). Each application is unique per user x jobPosting. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## JobPosting Data Object Job posting entity representing an open position with a company. Created/managed by company admins or recruiters. Fields include companyId, postedByUserId, title, details, requirements, employment type, salary, deadline, etc. ### JobPosting Data Object Properties JobPosting data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `description` | Text | false | Yes | No | - | | `title` | String | false | Yes | No | - | | `applicationDeadline` | Date | false | No | No | - | | `companyId` | ID | false | No | No | - | | `employmentType` | Enum | false | Yes | No | - | | `postedByUserId` | ID | false | Yes | No | - | | `salaryRange` | String | false | No | No | - | | `location` | String | false | No | No | - | | `visibility` | Enum | false | Yes | No | - | | `workplaceType` | Enum | false | Yes | No | - | | `status` | Enum | false | Yes | No | - | | `companyName` | String | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **employmentType**: [full_time, part_time, contract, internship, volunteer, other, temporary] - **visibility**: [public, private] - **workplaceType**: [on_site, remote, hybrid] - **status**: [active, closed] ### Relation Properties `companyId` `postedByUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **companyId**: ID Relation to `company`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **postedByUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `title` `applicationDeadline` `companyId` `employmentType` `postedByUserId` `location` `visibility` `workplaceType` `status` `companyName` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **title**: String has a filter named `title` - **applicationDeadline**: Date has a filter named `applicationDeadline` - **companyId**: ID has a filter named `companyId` - **employmentType**: Enum has a filter named `employmentType` - **postedByUserId**: ID has a filter named `postedByUserId` - **location**: String has a filter named `location` - **visibility**: Enum has a filter named `visibility` - **workplaceType**: Enum has a filter named `workplaceType` - **status**: Enum has a filter named `status` - **companyName**: String has a filter named `companyName` ## JobApplication Data Object Record of a user applying for a specific jobPosting (tracks application/resume/status/audit). Each application is unique per user x jobPosting. ### JobApplication Data Object Properties JobApplication data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `jobPostingId` | ID | false | Yes | No | - | | `applicantUserId` | ID | false | Yes | No | - | | `coverLetter` | Text | false | No | No | - | | `resumeUrl` | String | false | No | No | - | | `lastStatusUpdateAt` | Date | false | Yes | No | - | | `status` | Enum | false | Yes | No | - | | `appliedAt` | Date | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [submitted, in_review, accepted, rejected] ### Relation Properties `jobPostingId` `applicantUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **jobPostingId**: ID Relation to `jobPosting`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **applicantUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `jobPostingId` `applicantUserId` `lastStatusUpdateAt` `status` `appliedAt` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **jobPostingId**: ID has a filter named `jobPostingId` - **applicantUserId**: ID has a filter named `applicantUserId` - **lastStatusUpdateAt**: Date has a filter named `lastStatusUpdateAt` - **status**: Enum has a filter named `status` - **appliedAt**: Date has a filter named `appliedAt` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### JobPosting Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createJobPosting` | `/v1/jobpostings` | Auto | | Update | `updateJobPosting` | `/v1/jobpostings/:jobPostingId` | Auto | | Delete | `deleteJobPosting` | `/v1/jobpostings/:jobPostingId` | Auto | | Get | `getJobPosting` | `/v1/jobpostings/:jobPostingId` | Auto | | List | `listJobPostings` | `/v1/jobpostings` | Auto | ### JobApplication Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createJobApplication` | `/v1/jobapplications` | Auto | | Update | `updateJobApplication` | `/v1/jobapplications/:jobApplicationId` | Auto | | Delete | `deleteJobApplication` | `/v1/jobapplications/:jobApplicationId` | Auto | | Get | `getJobApplication` | `/v1/jobapplications/:jobApplicationId` | Auto | | List | `listJobApplications` | `/v1/jobapplications` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Delete Jobapplication` API Delete (soft) job application. Only applicant or admin for the job's company may delete. **Rest Route** The `deleteJobApplication` API REST controller can be triggered via the following route: `/v1/jobapplications/:jobApplicationId` **Rest Request Parameters** The `deleteJobApplication` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobApplicationId | ID | true | request.params?.["jobApplicationId"] | **jobApplicationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/jobapplications/:jobApplicationId** ```js axios({ method: 'DELETE', url: `/v1/jobapplications/${jobApplicationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobApplication", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "jobApplication": { "id": "ID", "jobPostingId": "ID", "applicantUserId": "ID", "coverLetter": "Text", "resumeUrl": "String", "lastStatusUpdateAt": "Date", "status": "Enum", "status_idx": "Integer", "appliedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Jobapplication` API Get job application record. Only applicant or admin of company may view. **Rest Route** The `getJobApplication` API REST controller can be triggered via the following route: `/v1/jobapplications/:jobApplicationId` **Rest Request Parameters** The `getJobApplication` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobApplicationId | ID | true | request.params?.["jobApplicationId"] | **jobApplicationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/jobapplications/:jobApplicationId** ```js axios({ method: 'GET', url: `/v1/jobapplications/${jobApplicationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobApplication", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "jobApplication": { "id": "ID", "jobPostingId": "ID", "applicantUserId": "ID", "coverLetter": "Text", "resumeUrl": "String", "lastStatusUpdateAt": "Date", "status": "Enum", "status_idx": "Integer", "appliedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Jobposting` API Update job posting fields. Only company admins for companyId may update. Ownership enforced. Edits forbidden after deadline if desired. **Rest Route** The `updateJobPosting` API REST controller can be triggered via the following route: `/v1/jobpostings/:jobPostingId` **Rest Request Parameters** The `updateJobPosting` api has got 12 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobPostingId | ID | true | request.params?.["jobPostingId"] | | description | Text | true | request.body?.["description"] | | title | String | true | request.body?.["title"] | | applicationDeadline | Date | false | request.body?.["applicationDeadline"] | | companyId | ID | true | request.body?.["companyId"] | | employmentType | Enum | true | request.body?.["employmentType"] | | salaryRange | String | false | request.body?.["salaryRange"] | | location | String | false | request.body?.["location"] | | visibility | Enum | true | request.body?.["visibility"] | | workplaceType | Enum | true | request.body?.["workplaceType"] | | status | Enum | true | request.body?.["status"] | | companyName | String | true | request.body?.["companyName"] | **jobPostingId** : This id paremeter is used to select the required data object that will be updated **description** : **title** : **applicationDeadline** : **companyId** : **employmentType** : **salaryRange** : **location** : **visibility** : **workplaceType** : **status** : **companyName** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/jobpostings/:jobPostingId** ```js axios({ method: 'PATCH', url: `/v1/jobpostings/${jobPostingId}`, data: { description:"Text", title:"String", applicationDeadline:"Date", companyId:"ID", employmentType:"Enum", salaryRange:"String", location:"String", visibility:"Enum", workplaceType:"Enum", status:"Enum", companyName:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobPosting", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "jobPosting": { "id": "ID", "description": "Text", "title": "String", "applicationDeadline": "Date", "companyId": "ID", "employmentType": "Enum", "employmentType_idx": "Integer", "postedByUserId": "ID", "salaryRange": "String", "location": "String", "visibility": "Enum", "visibility_idx": "Integer", "workplaceType": "Enum", "workplaceType_idx": "Integer", "status": "Enum", "status_idx": "Integer", "companyName": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Jobposting` API Delete (soft) a job posting. Only admin for companyId may delete. **Rest Route** The `deleteJobPosting` API REST controller can be triggered via the following route: `/v1/jobpostings/:jobPostingId` **Rest Request Parameters** The `deleteJobPosting` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobPostingId | ID | true | request.params?.["jobPostingId"] | **jobPostingId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/jobpostings/:jobPostingId** ```js axios({ method: 'DELETE', url: `/v1/jobpostings/${jobPostingId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobPosting", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "jobPosting": { "id": "ID", "description": "Text", "title": "String", "applicationDeadline": "Date", "companyId": "ID", "employmentType": "Enum", "employmentType_idx": "Integer", "postedByUserId": "ID", "salaryRange": "String", "location": "String", "visibility": "Enum", "visibility_idx": "Integer", "workplaceType": "Enum", "workplaceType_idx": "Integer", "status": "Enum", "status_idx": "Integer", "companyName": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Jobposting` API Fetch a job posting by ID. Publicly visible if visibility=public, else only viewable by admins of company. **Rest Route** The `getJobPosting` API REST controller can be triggered via the following route: `/v1/jobpostings/:jobPostingId` **Rest Request Parameters** The `getJobPosting` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobPostingId | ID | true | request.params?.["jobPostingId"] | **jobPostingId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/jobpostings/:jobPostingId** ```js axios({ method: 'GET', url: `/v1/jobpostings/${jobPostingId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobPosting", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "jobPosting": { "id": "ID", "description": "Text", "title": "String", "applicationDeadline": "Date", "companyId": "ID", "employmentType": "Enum", "employmentType_idx": "Integer", "postedByUserId": "ID", "salaryRange": "String", "location": "String", "visibility": "Enum", "visibility_idx": "Integer", "workplaceType": "Enum", "workplaceType_idx": "Integer", "status": "Enum", "status_idx": "Integer", "companyName": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Jobapplication` API Update job application (status/by admin, or resume/cover by applicant, limited). Only admins/recruiters for job's company, or applicant, may update. Status can only move forward, not revert to submitted. **Rest Route** The `updateJobApplication` API REST controller can be triggered via the following route: `/v1/jobapplications/:jobApplicationId` **Rest Request Parameters** The `updateJobApplication` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobApplicationId | ID | true | request.params?.["jobApplicationId"] | | coverLetter | Text | false | request.body?.["coverLetter"] | | resumeUrl | String | false | request.body?.["resumeUrl"] | | status | Enum | true | request.body?.["status"] | **jobApplicationId** : This id paremeter is used to select the required data object that will be updated **coverLetter** : **resumeUrl** : **status** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/jobapplications/:jobApplicationId** ```js axios({ method: 'PATCH', url: `/v1/jobapplications/${jobApplicationId}`, data: { coverLetter:"Text", resumeUrl:"String", status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobApplication", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "jobApplication": { "id": "ID", "jobPostingId": "ID", "applicantUserId": "ID", "coverLetter": "Text", "resumeUrl": "String", "lastStatusUpdateAt": "Date", "status": "Enum", "status_idx": "Integer", "appliedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Jobapplication` API Submit a job application for a jobPosting (by logged-in user). Only if not already applied, and before deadline. Sets status=submitted. **Rest Route** The `createJobApplication` API REST controller can be triggered via the following route: `/v1/jobapplications` **Rest Request Parameters** The `createJobApplication` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | jobPostingId | ID | true | request.body?.["jobPostingId"] | | coverLetter | Text | false | request.body?.["coverLetter"] | | resumeUrl | String | false | request.body?.["resumeUrl"] | | status | Enum | true | request.body?.["status"] | **jobPostingId** : **coverLetter** : **resumeUrl** : **status** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/jobapplications** ```js axios({ method: 'POST', url: '/v1/jobapplications', data: { jobPostingId:"ID", coverLetter:"Text", resumeUrl:"String", status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobApplication", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "jobApplication": { "id": "ID", "jobPostingId": "ID", "applicantUserId": "ID", "coverLetter": "Text", "resumeUrl": "String", "lastStatusUpdateAt": "Date", "status": "Enum", "status_idx": "Integer", "appliedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Jobpostings` API List job postings. Public jobs visible to all; private jobs visible only to company admins or recruiters. **Rest Route** The `listJobPostings` API REST controller can be triggered via the following route: `/v1/jobpostings` **Rest Request Parameters** **Filter Parameters** The `listJobPostings` api supports 10 optional filter parameters for filtering list results: **title** (`String`): Filter by title - Single (partial match, case-insensitive): `?title=` - Multiple: `?title=&title=` - Null: `?title=null` **applicationDeadline** (`Date`): Filter by applicationDeadline - Single date: `?applicationDeadline=2024-01-15` - Multiple dates: `?applicationDeadline=2024-01-15&applicationDeadline=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?applicationDeadline=null` **companyId** (`ID`): Filter by companyId - Single: `?companyId=` - Multiple: `?companyId=&companyId=` - Null: `?companyId=null` **employmentType** (`Enum`): Filter by employmentType - Single: `?employmentType=` (case-insensitive) - Multiple: `?employmentType=&employmentType=` - Null: `?employmentType=null` **postedByUserId** (`ID`): Filter by postedByUserId - Single: `?postedByUserId=` - Multiple: `?postedByUserId=&postedByUserId=` - Null: `?postedByUserId=null` **location** (`String`): Filter by location - Single (partial match, case-insensitive): `?location=` - Multiple: `?location=&location=` - Null: `?location=null` **visibility** (`Enum`): Filter by visibility - Single: `?visibility=` (case-insensitive) - Multiple: `?visibility=&visibility=` - Null: `?visibility=null` **workplaceType** (`Enum`): Filter by workplaceType - Single: `?workplaceType=` (case-insensitive) - Multiple: `?workplaceType=&workplaceType=` - Null: `?workplaceType=null` **status** (`Enum`): Filter by status - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **companyName** (`String`): Filter by companyName - Single (partial match, case-insensitive): `?companyName=` - Multiple: `?companyName=&companyName=` - Null: `?companyName=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/jobpostings** ```js axios({ method: 'GET', url: '/v1/jobpostings', data: { }, params: { // Filter parameters (see Filter Parameters section above) // title: '' // Filter by title // applicationDeadline: '' // Filter by applicationDeadline // companyId: '' // Filter by companyId // employmentType: '' // Filter by employmentType // postedByUserId: '' // Filter by postedByUserId // location: '' // Filter by location // visibility: '' // Filter by visibility // workplaceType: '' // Filter by workplaceType // status: '' // Filter by status // companyName: '' // Filter by companyName } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobPostings", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "jobPostings": [ { "id": "ID", "description": "Text", "title": "String", "applicationDeadline": "Date", "companyId": "ID", "employmentType": "Enum", "employmentType_idx": "Integer", "postedByUserId": "ID", "salaryRange": "String", "location": "String", "visibility": "Enum", "visibility_idx": "Integer", "workplaceType": "Enum", "workplaceType_idx": "Integer", "status": "Enum", "status_idx": "Integer", "companyName": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Jobapplications` API List job applications. Applicants see their own; admins of job's company can view all for their jobs; supports filter by status, job and applicant. **Rest Route** The `listJobApplications` API REST controller can be triggered via the following route: `/v1/jobapplications` **Rest Request Parameters** **Filter Parameters** The `listJobApplications` api supports 5 optional filter parameters for filtering list results: **jobPostingId** (`ID`): Filter by jobPostingId - Single: `?jobPostingId=` - Multiple: `?jobPostingId=&jobPostingId=` - Null: `?jobPostingId=null` **applicantUserId** (`ID`): Filter by applicantUserId - Single: `?applicantUserId=` - Multiple: `?applicantUserId=&applicantUserId=` - Null: `?applicantUserId=null` **lastStatusUpdateAt** (`Date`): Filter by lastStatusUpdateAt - Single date: `?lastStatusUpdateAt=2024-01-15` - Multiple dates: `?lastStatusUpdateAt=2024-01-15&lastStatusUpdateAt=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?lastStatusUpdateAt=null` **status** (`Enum`): Filter by status - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **appliedAt** (`Date`): Filter by appliedAt - Single date: `?appliedAt=2024-01-15` - Multiple dates: `?appliedAt=2024-01-15&appliedAt=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?appliedAt=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/jobapplications** ```js axios({ method: 'GET', url: '/v1/jobapplications', data: { }, params: { // Filter parameters (see Filter Parameters section above) // jobPostingId: '' // Filter by jobPostingId // applicantUserId: '' // Filter by applicantUserId // lastStatusUpdateAt: '' // Filter by lastStatusUpdateAt // status: '' // Filter by status // appliedAt: '' // Filter by appliedAt } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobApplications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "jobApplications": [ { "id": "ID", "jobPostingId": "ID", "applicantUserId": "ID", "coverLetter": "Text", "resumeUrl": "String", "lastStatusUpdateAt": "Date", "status": "Enum", "status_idx": "Integer", "appliedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Jobposting` API Create a new job posting. Only company admins/recruiters for companyId can create. postedByUserId set from session. **Rest Route** The `createJobPosting` API REST controller can be triggered via the following route: `/v1/jobpostings` **Rest Request Parameters** The `createJobPosting` api has got 11 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | description | Text | true | request.body?.["description"] | | title | String | true | request.body?.["title"] | | applicationDeadline | Date | false | request.body?.["applicationDeadline"] | | companyId | ID | false | request.body?.["companyId"] | | employmentType | Enum | true | request.body?.["employmentType"] | | salaryRange | String | false | request.body?.["salaryRange"] | | location | String | false | request.body?.["location"] | | visibility | Enum | true | request.body?.["visibility"] | | workplaceType | Enum | true | request.body?.["workplaceType"] | | status | Enum | true | request.body?.["status"] | | companyName | String | true | request.body?.["companyName"] | **description** : **title** : **applicationDeadline** : **companyId** : **employmentType** : **salaryRange** : **location** : **visibility** : **workplaceType** : **status** : **companyName** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/jobpostings** ```js axios({ method: 'POST', url: '/v1/jobpostings', data: { description:"Text", title:"String", applicationDeadline:"Date", companyId:"ID", employmentType:"Enum", salaryRange:"String", location:"String", visibility:"Enum", workplaceType:"Enum", status:"Enum", companyName:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "jobPosting", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "jobPosting": { "id": "ID", "description": "Text", "title": "String", "applicationDeadline": "Date", "companyId": "ID", "employmentType": "Enum", "employmentType_idx": "Integer", "postedByUserId": "ID", "salaryRange": "String", "location": "String", "visibility": "Enum", "visibility_idx": "Integer", "workplaceType": "Enum", "workplaceType_idx": "Integer", "status": "Enum", "status_idx": "Integer", "companyName": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 8 - Networking Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of networking ## Service Access Networking service management is handled through service specific base urls. Networking service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the networking service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/networking-api` * **Staging:** `https://linkedin-stage.mindbricks.co/networking-api` * **Production:** `https://linkedin.mindbricks.co/networking-api` ## Scope **Networking Service Description** Handles professional networking logic for user-to-user connections: manages connection requests, accepted relationships, listing/removal, permissions, and state transitions. Publishes connection lifecycle events for notification... Networking service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`connection` Data Object**: Represents a single established user-to-user professional relationship (mutual connection). One record per unordered user pair, deleted on disconnect.. **`connectionRequest` Data Object**: Tracks a user's request to connect with another user, supporting request/accept/reject/cancel, with audit timestamps. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Connection Data Object Represents a single established user-to-user professional relationship (mutual connection). One record per unordered user pair, deleted on disconnect.. ### Connection Data Object Properties Connection data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `connectedSince` | Date | false | Yes | No | - | | `userId1` | ID | false | Yes | No | - | | `userId2` | ID | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId1` `userId2` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId1**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **userId2**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ## ConnectionRequest Data Object Tracks a user's request to connect with another user, supporting request/accept/reject/cancel, with audit timestamps. ### ConnectionRequest Data Object Properties ConnectionRequest data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `receiverUserId` | ID | false | Yes | No | - | | `senderUserId` | ID | false | Yes | No | - | | `sentAt` | Date | false | Yes | No | - | | `status` | Enum | false | Yes | No | - | | `respondedAt` | Date | false | No | No | - | | `message` | String | false | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [pending, accepted, rejected] ### Relation Properties `receiverUserId` `senderUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **receiverUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **senderUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **status**: Enum has a filter named `status` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### Connection Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createConnection` | `/v1/connections` | Auto | | Update | _none_ | - | Auto | | Delete | `deleteConnection` | `/v1/connections/:connectionId` | Auto | | Get | `getConnection` | `/v1/connections/:connectionId` | Auto | | List | `listConnections` | `/v1/connections` | Auto | ### ConnectionRequest Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createConnectionRequest` | `/v1/connectionrequests` | Auto | | Update | `updateConnectionRequest` | `/v1/connectionrequests/:connectionRequestId` | Auto | | Delete | `deleteConnectionRequest` | `/v1/connectionrequests/:connectionRequestId` | Auto | | Get | `getConnectionRequest` | `/v1/connectionrequests/:connectionRequestId` | Auto | | List | `listConnectionRequests` | `/v1/connectionrequests` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Create Connection` API Create Connection **Rest Route** The `createConnection` API REST controller can be triggered via the following route: `/v1/connections` **Rest Request Parameters** The `createConnection` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId1 | ID | true | request.body?.["userId1"] | | userId2 | ID | true | request.body?.["userId2"] | **userId1** : **userId2** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/connections** ```js axios({ method: 'POST', url: '/v1/connections', data: { userId1:"ID", userId2:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connection", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "connection": { "id": "ID", "connectedSince": "Date", "userId1": "ID", "userId2": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Connectionrequest` API Sender or receiver may cancel/delete a connection request (soft-delete). **Rest Route** The `deleteConnectionRequest` API REST controller can be triggered via the following route: `/v1/connectionrequests/:connectionRequestId` **Rest Request Parameters** The `deleteConnectionRequest` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | connectionRequestId | ID | true | request.params?.["connectionRequestId"] | **connectionRequestId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/connectionrequests/:connectionRequestId** ```js axios({ method: 'DELETE', url: `/v1/connectionrequests/${connectionRequestId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connectionRequest", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "connectionRequest": { "id": "ID", "receiverUserId": "ID", "senderUserId": "ID", "sentAt": "Date", "status": "Enum", "status_idx": "Integer", "respondedAt": "Date", "message": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Connectionrequest` API Allows receiver of a pending connection request to accept or reject request. **Rest Route** The `updateConnectionRequest` API REST controller can be triggered via the following route: `/v1/connectionrequests/:connectionRequestId` **Rest Request Parameters** The `updateConnectionRequest` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | connectionRequestId | ID | true | request.params?.["connectionRequestId"] | | status | Enum | true | request.body?.["status"] | | respondedAt | Date | false | request.body?.["respondedAt"] | **connectionRequestId** : This id paremeter is used to select the required data object that will be updated **status** : **respondedAt** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/connectionrequests/:connectionRequestId** ```js axios({ method: 'PATCH', url: `/v1/connectionrequests/${connectionRequestId}`, data: { status:"Enum", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connectionRequest", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "connectionRequest": { "id": "ID", "receiverUserId": "ID", "senderUserId": "ID", "sentAt": "Date", "status": "Enum", "status_idx": "Integer", "respondedAt": "Date", "message": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Connections` API List all active connections where session user is a participant. **Rest Route** The `listConnections` API REST controller can be triggered via the following route: `/v1/connections` **Rest Request Parameters** The `listConnections` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/connections** ```js axios({ method: 'GET', url: '/v1/connections', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connections", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "connections": [ { "id": "ID", "connectedSince": "Date", "userId1": "ID", "userId2": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Connectionrequests` API List connection requests involving current user, filterable by status (pending, accepted, rejected). **Rest Route** The `listConnectionRequests` API REST controller can be triggered via the following route: `/v1/connectionrequests` **Rest Request Parameters** **Filter Parameters** The `listConnectionRequests` api supports 1 optional filter parameter for filtering list results: **status** (`Enum`): Filter by status - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/connectionrequests** ```js axios({ method: 'GET', url: '/v1/connectionrequests', data: { }, params: { // Filter parameters (see Filter Parameters section above) // status: '' // Filter by status } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connectionRequests", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "connectionRequests": [ { "id": "ID", "receiverUserId": "ID", "senderUserId": "ID", "sentAt": "Date", "status": "Enum", "status_idx": "Integer", "respondedAt": "Date", "message": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Connectionrequest` API Send a new connection request from logged-in user to another user. **Rest Route** The `createConnectionRequest` API REST controller can be triggered via the following route: `/v1/connectionrequests` **Rest Request Parameters** The `createConnectionRequest` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | receiverUserId | ID | true | request.body?.["receiverUserId"] | | status | Enum | true | request.body?.["status"] | | respondedAt | Date | false | request.body?.["respondedAt"] | | message | String | false | request.body?.["message"] | **receiverUserId** : **status** : **respondedAt** : **message** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/connectionrequests** ```js axios({ method: 'POST', url: '/v1/connectionrequests', data: { receiverUserId:"ID", status:"Enum", respondedAt:"Date", message:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connectionRequest", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "connectionRequest": { "id": "ID", "receiverUserId": "ID", "senderUserId": "ID", "sentAt": "Date", "status": "Enum", "status_idx": "Integer", "respondedAt": "Date", "message": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Connection` API Break (delete) the connection between two users. Either user may disconnect. **Rest Route** The `deleteConnection` API REST controller can be triggered via the following route: `/v1/connections/:connectionId` **Rest Request Parameters** The `deleteConnection` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | connectionId | ID | true | request.params?.["connectionId"] | **connectionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/connections/:connectionId** ```js axios({ method: 'DELETE', url: `/v1/connections/${connectionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connection", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "connection": { "id": "ID", "connectedSince": "Date", "userId1": "ID", "userId2": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Connectionrequest` API Get a specific connection request by ID if sender/receiver. **Rest Route** The `getConnectionRequest` API REST controller can be triggered via the following route: `/v1/connectionrequests/:connectionRequestId` **Rest Request Parameters** The `getConnectionRequest` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | connectionRequestId | ID | true | request.params?.["connectionRequestId"] | **connectionRequestId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/connectionrequests/:connectionRequestId** ```js axios({ method: 'GET', url: `/v1/connectionrequests/${connectionRequestId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connectionRequest", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "connectionRequest": { "id": "ID", "receiverUserId": "ID", "senderUserId": "ID", "sentAt": "Date", "status": "Enum", "status_idx": "Integer", "respondedAt": "Date", "message": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Connection` API Get connection between session user and another user (if exists, not soft-deleted). **Rest Route** The `getConnection` API REST controller can be triggered via the following route: `/v1/connections/:connectionId` **Rest Request Parameters** The `getConnection` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | connectionId | ID | true | request.params?.["connectionId"] | **connectionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/connections/:connectionId** ```js axios({ method: 'GET', url: `/v1/connections/${connectionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "connection", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "connection": { "id": "ID", "connectedSince": "Date", "userId1": "ID", "userId2": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 9 - Company Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of company ## Service Access Company service management is handled through service specific base urls. Company service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the company service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/company-api` * **Staging:** `https://linkedin-stage.mindbricks.co/company-api` * **Production:** `https://linkedin.mindbricks.co/company-api` ## Scope **Company Service Description** Handles company profiles, company admin assignments, company following, and posting company updates/news. Enables professionals to follow companies, get updates, and enables admins to manage company presence.. Company service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`companyFollower` Data Object**: Tracks when a user follows a company to receive updates. Append-only, deletes for unfollow. **`companyUpdate` Data Object**: A post/news update created by company admin and visible to followers depending on visibility. **`company` Data Object**: Represents a company profile and brand presence/pages on the network. **`companyAdmin` Data Object**: Tracks which users are assigned as admins for a company, allowing them to manage the company page and edits. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## CompanyFollower Data Object Tracks when a user follows a company to receive updates. Append-only, deletes for unfollow. ### CompanyFollower Data Object Properties CompanyFollower data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `userId` | ID | false | Yes | No | - | | `companyId` | ID | false | Yes | No | - | | `followedAt` | Date | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId` `companyId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **companyId**: ID Relation to `company`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `userId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` ## CompanyUpdate Data Object A post/news update created by company admin and visible to followers depending on visibility. ### CompanyUpdate Data Object Properties CompanyUpdate data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `companyId` | ID | false | Yes | No | - | | `content` | Text | false | Yes | No | - | | `authorUserId` | ID | false | Yes | No | - | | `attachmentUrls` | String | true | No | No | - | | `visibility` | Enum | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `attachmentUrls` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **visibility**: [public, private] ### Relation Properties `companyId` `authorUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **companyId**: ID Relation to `company`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **authorUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `visibility` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **visibility**: Enum has a filter named `visibility` ## Company Data Object Represents a company profile and brand presence/pages on the network. ### Company Data Object Properties Company data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `name` | String | false | Yes | No | - | | `website` | String | false | No | No | - | | `location` | String | false | No | No | - | | `logoUrl` | String | false | No | No | - | | `pageVisibility` | Enum | false | Yes | No | - | | `createdByUserId` | ID | false | Yes | No | - | | `description` | Text | false | No | No | - | | `industry` | String | false | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **pageVisibility**: [public, private] ### Filter Properties `name` `location` `pageVisibility` `industry` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **name**: String has a filter named `name` - **location**: String has a filter named `location` - **pageVisibility**: Enum has a filter named `pageVisibility` - **industry**: String has a filter named `industry` ## CompanyAdmin Data Object Tracks which users are assigned as admins for a company, allowing them to manage the company page and edits. ### CompanyAdmin Data Object Properties CompanyAdmin data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `assignedAt` | Date | false | Yes | No | - | | `userId` | ID | false | Yes | No | - | | `companyId` | ID | false | Yes | No | - | | `assignedBy` | ID | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId` `companyId` `assignedBy` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **companyId**: ID Relation to `company`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **assignedBy**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `userId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### CompanyFollower Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `followCompany` | `/v1/followcompany` | Auto | | Update | _none_ | - | Auto | | Delete | `unfollowCompany` | `/v1/unfollowcompany/:companyFollowerId` | Auto | | Get | `getCompanyFollower` | `/v1/companyfollowers/:companyFollowerId` | Auto | | List | `listCompanyFollowers` | `/v1/companyfollowers` | Auto | ### CompanyUpdate Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createCompanyUpdate` | `/v1/companyupdates` | Auto | | Update | `updateCompanyUpdate` | `/v1/companyupdates/:companyUpdateId` | Auto | | Delete | `deleteCompanyUpdate` | `/v1/companyupdates/:companyUpdateId` | Auto | | Get | `getCompanyUpdate` | `/v1/companyupdates/:companyUpdateId` | Auto | | List | `listCompanyUpdates` | `/v1/companyupdates` | Auto | ### Company Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createCompany` | `/v1/companies` | Auto | | Update | `updateCompany` | `/v1/companies/:companyId` | Auto | | Delete | `deleteCompany` | `/v1/companies/:companyId` | Auto | | Get | `getCompany` | `/v1/companies/:companyId` | Auto | | List | `listCompanies` | `/v1/companies` | Auto | ### CompanyAdmin Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `assignCompanyAdmin` | `/v1/assigncompanyadmin` | Auto | | Update | _none_ | - | Auto | | Delete | `removeCompanyAdmin` | `/v1/removecompanyadmin/:companyAdminId` | Auto | | Get | `getCompanyAdmin` | `/v1/companyadmins/:companyAdminId` | Auto | | List | `listCompanyAdmins` | `/v1/companyadmins` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Get Companyadmin` API Get company admin record by ID. Only admins can query of their company. **Rest Route** The `getCompanyAdmin` API REST controller can be triggered via the following route: `/v1/companyadmins/:companyAdminId` **Rest Request Parameters** The `getCompanyAdmin` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyAdminId | ID | true | request.params?.["companyAdminId"] | **companyAdminId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyadmins/:companyAdminId** ```js axios({ method: 'GET', url: `/v1/companyadmins/${companyAdminId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyAdmin", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "companyAdmin": { "id": "ID", "assignedAt": "Date", "userId": "ID", "companyId": "ID", "assignedBy": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Follow Company` API Follow a company. Adds entry to companyFollower. Any logged-in user may follow. Cannot follow twice. **Rest Route** The `followCompany` API REST controller can be triggered via the following route: `/v1/followcompany` **Rest Request Parameters** The `followCompany` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.body?.["userId"] | | companyId | ID | true | request.body?.["companyId"] | | followedAt | Date | true | request.body?.["followedAt"] | **userId** : **companyId** : **followedAt** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/followcompany** ```js axios({ method: 'POST', url: '/v1/followcompany', data: { userId:"ID", companyId:"ID", followedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyFollower", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "companyFollower": { "id": "ID", "userId": "ID", "companyId": "ID", "followedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Remove Companyadmin` API Removes admin rights from a user for a company. Can only be performed by current admin, not self-removal unless last admin? **Rest Route** The `removeCompanyAdmin` API REST controller can be triggered via the following route: `/v1/removecompanyadmin/:companyAdminId` **Rest Request Parameters** The `removeCompanyAdmin` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyAdminId | ID | true | request.params?.["companyAdminId"] | **companyAdminId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/removecompanyadmin/:companyAdminId** ```js axios({ method: 'DELETE', url: `/v1/removecompanyadmin/${companyAdminId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyAdmin", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "companyAdmin": { "id": "ID", "assignedAt": "Date", "userId": "ID", "companyId": "ID", "assignedBy": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Company` API Creates a new company profile (page). User initiating the company becomes initial admin (enforced in workflow). **Rest Route** The `createCompany` API REST controller can be triggered via the following route: `/v1/companies` **Rest Request Parameters** The `createCompany` api has got 8 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.["name"] | | website | String | false | request.body?.["website"] | | location | String | false | request.body?.["location"] | | logoUrl | String | false | request.body?.["logoUrl"] | | pageVisibility | Enum | true | request.body?.["pageVisibility"] | | createdByUserId | ID | true | request.body?.["createdByUserId"] | | description | Text | false | request.body?.["description"] | | industry | String | false | request.body?.["industry"] | **name** : **website** : **location** : **logoUrl** : **pageVisibility** : **createdByUserId** : **description** : **industry** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/companies** ```js axios({ method: 'POST', url: '/v1/companies', data: { name:"String", website:"String", location:"String", logoUrl:"String", pageVisibility:"Enum", createdByUserId:"ID", description:"Text", industry:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "company", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "company": { "id": "ID", "name": "String", "website": "String", "location": "String", "logoUrl": "String", "pageVisibility": "Enum", "pageVisibility_idx": "Integer", "createdByUserId": "ID", "description": "Text", "industry": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Company` API Get a company page by ID. If public, anyone can view. If private, only admin/followers. **Rest Route** The `getCompany` API REST controller can be triggered via the following route: `/v1/companies/:companyId` **Rest Request Parameters** The `getCompany` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyId | ID | true | request.params?.["companyId"] | **companyId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companies/:companyId** ```js axios({ method: 'GET', url: `/v1/companies/${companyId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "company", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "company": { "id": "ID", "name": "String", "website": "String", "location": "String", "logoUrl": "String", "pageVisibility": "Enum", "pageVisibility_idx": "Integer", "createdByUserId": "ID", "description": "Text", "industry": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Companies` API List all (optionally filtered) companies, e.g. for directory/search, subject to visibility. **Rest Route** The `listCompanies` API REST controller can be triggered via the following route: `/v1/companies` **Rest Request Parameters** **Filter Parameters** The `listCompanies` api supports 4 optional filter parameters for filtering list results: **name** (`String`): Filter by name - Single (partial match, case-insensitive): `?name=` - Multiple: `?name=&name=` - Null: `?name=null` **location** (`String`): Filter by location - Single (partial match, case-insensitive): `?location=` - Multiple: `?location=&location=` - Null: `?location=null` **pageVisibility** (`Enum`): Filter by pageVisibility - Single: `?pageVisibility=` (case-insensitive) - Multiple: `?pageVisibility=&pageVisibility=` - Null: `?pageVisibility=null` **industry** (`String`): Filter by industry - Single (partial match, case-insensitive): `?industry=` - Multiple: `?industry=&industry=` - Null: `?industry=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companies** ```js axios({ method: 'GET', url: '/v1/companies', data: { }, params: { // Filter parameters (see Filter Parameters section above) // name: '' // Filter by name // location: '' // Filter by location // pageVisibility: '' // Filter by pageVisibility // industry: '' // Filter by industry } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companies", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "companies": [ { "id": "ID", "name": "String", "website": "String", "location": "String", "logoUrl": "String", "pageVisibility": "Enum", "pageVisibility_idx": "Integer", "createdByUserId": "ID", "description": "Text", "industry": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Company` API Updates fields of a company page/profile. Only current company admin can update. **Rest Route** The `updateCompany` API REST controller can be triggered via the following route: `/v1/companies/:companyId` **Rest Request Parameters** The `updateCompany` api has got 9 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyId | ID | true | request.params?.["companyId"] | | name | String | false | request.body?.["name"] | | website | String | false | request.body?.["website"] | | location | String | false | request.body?.["location"] | | logoUrl | String | false | request.body?.["logoUrl"] | | pageVisibility | Enum | false | request.body?.["pageVisibility"] | | createdByUserId | ID | true | request.body?.["createdByUserId"] | | description | Text | false | request.body?.["description"] | | industry | String | false | request.body?.["industry"] | **companyId** : This id paremeter is used to select the required data object that will be updated **name** : **website** : **location** : **logoUrl** : **pageVisibility** : **createdByUserId** : **description** : **industry** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/companies/:companyId** ```js axios({ method: 'PATCH', url: `/v1/companies/${companyId}`, data: { name:"String", website:"String", location:"String", logoUrl:"String", pageVisibility:"Enum", createdByUserId:"ID", description:"Text", industry:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "company", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "company": { "id": "ID", "name": "String", "website": "String", "location": "String", "logoUrl": "String", "pageVisibility": "Enum", "pageVisibility_idx": "Integer", "createdByUserId": "ID", "description": "Text", "industry": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Company` API Deletes (soft-delete) a company page. Only current admin may delete. **Rest Route** The `deleteCompany` API REST controller can be triggered via the following route: `/v1/companies/:companyId` **Rest Request Parameters** The `deleteCompany` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyId | ID | true | request.params?.["companyId"] | **companyId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/companies/:companyId** ```js axios({ method: 'DELETE', url: `/v1/companies/${companyId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "company", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "company": { "id": "ID", "name": "String", "website": "String", "location": "String", "logoUrl": "String", "pageVisibility": "Enum", "pageVisibility_idx": "Integer", "createdByUserId": "ID", "description": "Text", "industry": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Assign Companyadmin` API Assigns a user as company admin. Must be called by an existing admin. Records assigning user and timestamp for audit. **Rest Route** The `assignCompanyAdmin` API REST controller can be triggered via the following route: `/v1/assigncompanyadmin` **Rest Request Parameters** The `assignCompanyAdmin` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | assignedAt | Date | true | request.body?.["assignedAt"] | | userId | ID | true | request.body?.["userId"] | | companyId | ID | true | request.body?.["companyId"] | | assignedBy | ID | true | request.body?.["assignedBy"] | **assignedAt** : **userId** : **companyId** : **assignedBy** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/assigncompanyadmin** ```js axios({ method: 'POST', url: '/v1/assigncompanyadmin', data: { assignedAt:"Date", userId:"ID", companyId:"ID", assignedBy:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyAdmin", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "companyAdmin": { "id": "ID", "assignedAt": "Date", "userId": "ID", "companyId": "ID", "assignedBy": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Companyadmins` API List all current admins for a given company. Only admins can query their company admin list. **Rest Route** The `listCompanyAdmins` API REST controller can be triggered via the following route: `/v1/companyadmins` **Rest Request Parameters** **Filter Parameters** The `listCompanyAdmins` api supports 1 optional filter parameter for filtering list results: **userId** (`ID`): Filter by userId - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyadmins** ```js axios({ method: 'GET', url: '/v1/companyadmins', data: { }, params: { // Filter parameters (see Filter Parameters section above) // userId: '' // Filter by userId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyAdmins", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "companyAdmins": [ { "id": "ID", "assignedAt": "Date", "userId": "ID", "companyId": "ID", "assignedBy": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Companyupdate` API Get a company update/news post. Only public posts are visible to all, private are visible to company followers and company admins. **Rest Route** The `getCompanyUpdate` API REST controller can be triggered via the following route: `/v1/companyupdates/:companyUpdateId` **Rest Request Parameters** The `getCompanyUpdate` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyUpdateId | ID | true | request.params?.["companyUpdateId"] | **companyUpdateId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyupdates/:companyUpdateId** ```js axios({ method: 'GET', url: `/v1/companyupdates/${companyUpdateId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyUpdate", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "companyUpdate": { "id": "ID", "companyId": "ID", "content": "Text", "authorUserId": "ID", "attachmentUrls": "String", "visibility": "Enum", "visibility_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Unfollow Company` API Unfollow a company. Deletes companyFollower entry. Only current follower may unfollow. **Rest Route** The `unfollowCompany` API REST controller can be triggered via the following route: `/v1/unfollowcompany/:companyFollowerId` **Rest Request Parameters** The `unfollowCompany` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyFollowerId | ID | true | request.params?.["companyFollowerId"] | **companyFollowerId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/unfollowcompany/:companyFollowerId** ```js axios({ method: 'DELETE', url: `/v1/unfollowcompany/${companyFollowerId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyFollower", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "companyFollower": { "id": "ID", "userId": "ID", "companyId": "ID", "followedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Companyfollowers` API List all followers of a company. Only company admin can see list of all followers. **Rest Route** The `listCompanyFollowers` API REST controller can be triggered via the following route: `/v1/companyfollowers` **Rest Request Parameters** **Filter Parameters** The `listCompanyFollowers` api supports 1 optional filter parameter for filtering list results: **userId** (`ID`): Filter by userId - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyfollowers** ```js axios({ method: 'GET', url: '/v1/companyfollowers', data: { }, params: { // Filter parameters (see Filter Parameters section above) // userId: '' // Filter by userId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyFollowers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "companyFollowers": [ { "id": "ID", "userId": "ID", "companyId": "ID", "followedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Companyupdate` API Posts a company update/news. Only active admin of company may post on that company's behalf. **Rest Route** The `createCompanyUpdate` API REST controller can be triggered via the following route: `/v1/companyupdates` **Rest Request Parameters** The `createCompanyUpdate` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyId | ID | true | request.body?.["companyId"] | | content | Text | true | request.body?.["content"] | | authorUserId | ID | true | request.body?.["authorUserId"] | | attachmentUrls | String | false | request.body?.["attachmentUrls"] | | visibility | Enum | true | request.body?.["visibility"] | **companyId** : **content** : **authorUserId** : **attachmentUrls** : **visibility** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/companyupdates** ```js axios({ method: 'POST', url: '/v1/companyupdates', data: { companyId:"ID", content:"Text", authorUserId:"ID", attachmentUrls:"String", visibility:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyUpdate", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "companyUpdate": { "id": "ID", "companyId": "ID", "content": "Text", "authorUserId": "ID", "attachmentUrls": "String", "visibility": "Enum", "visibility_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Companyupdate` API Update company update post/news. Only author or company admins may update. **Rest Route** The `updateCompanyUpdate` API REST controller can be triggered via the following route: `/v1/companyupdates/:companyUpdateId` **Rest Request Parameters** The `updateCompanyUpdate` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyUpdateId | ID | true | request.params?.["companyUpdateId"] | | content | Text | false | request.body?.["content"] | | attachmentUrls | String | false | request.body?.["attachmentUrls"] | | visibility | Enum | false | request.body?.["visibility"] | **companyUpdateId** : This id paremeter is used to select the required data object that will be updated **content** : **attachmentUrls** : **visibility** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/companyupdates/:companyUpdateId** ```js axios({ method: 'PATCH', url: `/v1/companyupdates/${companyUpdateId}`, data: { content:"Text", attachmentUrls:"String", visibility:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyUpdate", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "companyUpdate": { "id": "ID", "companyId": "ID", "content": "Text", "authorUserId": "ID", "attachmentUrls": "String", "visibility": "Enum", "visibility_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Companyfollower` API Get a companyFollower record (for audit/profile/follower listing). Only follower/userId or company admin can get record. **Rest Route** The `getCompanyFollower` API REST controller can be triggered via the following route: `/v1/companyfollowers/:companyFollowerId` **Rest Request Parameters** The `getCompanyFollower` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyFollowerId | ID | true | request.params?.["companyFollowerId"] | **companyFollowerId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyfollowers/:companyFollowerId** ```js axios({ method: 'GET', url: `/v1/companyfollowers/${companyFollowerId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyFollower", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "companyFollower": { "id": "ID", "userId": "ID", "companyId": "ID", "followedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Companyupdate` API Delete (soft delete) a company update/news. Only author or current admin may delete. **Rest Route** The `deleteCompanyUpdate` API REST controller can be triggered via the following route: `/v1/companyupdates/:companyUpdateId` **Rest Request Parameters** The `deleteCompanyUpdate` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | companyUpdateId | ID | true | request.params?.["companyUpdateId"] | **companyUpdateId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/companyupdates/:companyUpdateId** ```js axios({ method: 'DELETE', url: `/v1/companyupdates/${companyUpdateId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyUpdate", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "companyUpdate": { "id": "ID", "companyId": "ID", "content": "Text", "authorUserId": "ID", "attachmentUrls": "String", "visibility": "Enum", "visibility_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Companyupdates` API List company updates/news for a company. Public updates are visible to all, private to followers/admins. **Rest Route** The `listCompanyUpdates` API REST controller can be triggered via the following route: `/v1/companyupdates` **Rest Request Parameters** **Filter Parameters** The `listCompanyUpdates` api supports 1 optional filter parameter for filtering list results: **visibility** (`Enum`): Filter by visibility - Single: `?visibility=` (case-insensitive) - Multiple: `?visibility=&visibility=` - Null: `?visibility=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/companyupdates** ```js axios({ method: 'GET', url: '/v1/companyupdates', data: { }, params: { // Filter parameters (see Filter Parameters section above) // visibility: '' // Filter by visibility } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "companyUpdates", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "companyUpdates": [ { "id": "ID", "companyId": "ID", "content": "Text", "authorUserId": "ID", "attachmentUrls": "String", "visibility": "Enum", "visibility_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 10 - Content Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of content ## Service Access Content service management is handled through service specific base urls. Content service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the content service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/content-api` * **Staging:** `https://linkedin-stage.mindbricks.co/content-api` * **Production:** `https://linkedin.mindbricks.co/content-api` ## Scope **Content Service Description** Handles creation, editing, and deletion of user posts (with attachments and visibility), user post feed aggregation, and post engagement (likes, comments). All with post-level visibility control (public/private).. Content service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`post` Data Object**: A user or company-authored post in the feed, with content, optional attachments, and public/private visibility. Belongs to a user (author) and optionally a company. **`like` Data Object**: A record of a user liking a specific post. Each user can like a post only once. Used for engagement counts and activity feeds. **`comment` Data Object**: A comment on a post. Can be a top-level or a reply to another comment (via parentCommentId). ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Post Data Object A user or company-authored post in the feed, with content, optional attachments, and public/private visibility. Belongs to a user (author) and optionally a company. ### Post Data Object Properties Post data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `content` | Text | false | Yes | No | - | | `companyId` | ID | false | No | No | - | | `authorUserId` | ID | false | Yes | No | - | | `visibility` | Enum | false | Yes | No | - | | `attachmentUrls` | String | true | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `attachmentUrls` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **visibility**: [public, private] ### Relation Properties `companyId` `authorUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **companyId**: ID Relation to `company`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **authorUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `companyId` `authorUserId` `visibility` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **companyId**: ID has a filter named `companyId` - **authorUserId**: ID has a filter named `authorUserId` - **visibility**: Enum has a filter named `visibility` ## Like Data Object A record of a user liking a specific post. Each user can like a post only once. Used for engagement counts and activity feeds. ### Like Data Object Properties Like data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `likedAt` | Date | false | Yes | No | - | | `postId` | ID | false | Yes | No | - | | `userId` | ID | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `postId` `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **postId**: ID Relation to `post`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `postId` `userId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **postId**: ID has a filter named `postId` - **userId**: ID has a filter named `userId` ## Comment Data Object A comment on a post. Can be a top-level or a reply to another comment (via parentCommentId). ### Comment Data Object Properties Comment data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `authorUserId` | ID | false | Yes | No | - | | `postId` | ID | false | Yes | No | - | | `content` | Text | false | Yes | No | - | | `parentCommentId` | ID | false | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `authorUserId` `postId` `parentCommentId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **authorUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **postId**: ID Relation to `post`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **parentCommentId**: ID Relation to `comment`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `postId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **postId**: ID has a filter named `postId` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### Post Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createPost` | `/v1/posts` | Auto | | Update | `updatePost` | `/v1/posts/:postId` | Auto | | Delete | `deletePost` | `/v1/posts/:postId` | Auto | | Get | `getPost` | `/v1/posts/:postId` | Auto | | List | `listPosts` | `/v1/posts` | Auto | ### Like Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `likePost` | `/v1/likepost` | Auto | | Update | _none_ | - | Auto | | Delete | `unlikePost` | `/v1/unlikepost/:likeId` | Auto | | Get | _none_ | - | Auto | | List | `listLikes` | `/v1/likes` | Auto | ### Comment Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createComment` | `/v1/comments` | Auto | | Update | `updateComment` | `/v1/comments/:commentId` | Auto | | Delete | `deleteComment` | `/v1/comments/:commentId` | Auto | | Get | `getComment` | `/v1/comments/:commentId` | Auto | | List | `listComments` | `/v1/comments` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Create Post` API Create a new post for the authenticated user. Visibility defaults to public. Posts can optionally belong to a company if author is a company admin. Attachments optional. **Rest Route** The `createPost` API REST controller can be triggered via the following route: `/v1/posts` **Rest Request Parameters** The `createPost` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | content | Text | true | request.body?.["content"] | | companyId | ID | false | request.body?.["companyId"] | | authorUserId | ID | true | request.body?.["authorUserId"] | | visibility | Enum | true | request.body?.["visibility"] | | attachmentUrls | String | false | request.body?.["attachmentUrls"] | **content** : **companyId** : **authorUserId** : **visibility** : **attachmentUrls** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/posts** ```js axios({ method: 'POST', url: '/v1/posts', data: { content:"Text", companyId:"ID", authorUserId:"ID", visibility:"Enum", attachmentUrls:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "post", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "post": { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Comment` API Update an existing comment. Only the author can update. **Rest Route** The `updateComment` API REST controller can be triggered via the following route: `/v1/comments/:commentId` **Rest Request Parameters** The `updateComment` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | commentId | ID | true | request.params?.["commentId"] | | content | Text | false | request.body?.["content"] | | parentCommentId | ID | false | request.body?.["parentCommentId"] | **commentId** : This id paremeter is used to select the required data object that will be updated **content** : **parentCommentId** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/comments/:commentId** ```js axios({ method: 'PATCH', url: `/v1/comments/${commentId}`, data: { content:"Text", parentCommentId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "comment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "comment": { "id": "ID", "authorUserId": "ID", "postId": "ID", "content": "Text", "parentCommentId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Posts` API List posts matching filters, honoring post visibility. Public posts shown to all; private posts only to owners. Supports filtering by author, company, and visibility. Feed aggregation is handled at higher BFF layer. **Rest Route** The `listPosts` API REST controller can be triggered via the following route: `/v1/posts` **Rest Request Parameters** **Filter Parameters** The `listPosts` api supports 3 optional filter parameters for filtering list results: **companyId** (`ID`): Filter by companyId - Single: `?companyId=` - Multiple: `?companyId=&companyId=` - Null: `?companyId=null` **authorUserId** (`ID`): Filter by authorUserId - Single: `?authorUserId=` - Multiple: `?authorUserId=&authorUserId=` - Null: `?authorUserId=null` **visibility** (`Enum`): Filter by visibility - Single: `?visibility=` (case-insensitive) - Multiple: `?visibility=&visibility=` - Null: `?visibility=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/posts** ```js axios({ method: 'GET', url: '/v1/posts', data: { }, params: { // Filter parameters (see Filter Parameters section above) // companyId: '' // Filter by companyId // authorUserId: '' // Filter by authorUserId // visibility: '' // Filter by visibility } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "posts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "posts": [ { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Like Post` API Like a post. User can like a post only once; duplicate likes prevented. **Rest Route** The `likePost` API REST controller can be triggered via the following route: `/v1/likepost` **Rest Request Parameters** The `likePost` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | postId | ID | true | request.body?.["postId"] | **postId** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/likepost** ```js axios({ method: 'POST', url: '/v1/likepost', data: { postId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "like", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "like": { "id": "ID", "likedAt": "Date", "postId": "ID", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Post` API Get a post by ID. Public posts visible to all. Private only visible to author or company admin (if company post). **Rest Route** The `getPost` API REST controller can be triggered via the following route: `/v1/posts/:postId` **Rest Request Parameters** The `getPost` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | postId | ID | true | request.params?.["postId"] | **postId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/posts/:postId** ```js axios({ method: 'GET', url: `/v1/posts/${postId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "post", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "post": { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Comment` API Add a new comment to a post. Can be top-level (parentCommentId null) or a reply. Only authenticated users can comment. **Rest Route** The `createComment` API REST controller can be triggered via the following route: `/v1/comments` **Rest Request Parameters** The `createComment` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | postId | ID | true | request.body?.["postId"] | | content | Text | true | request.body?.["content"] | | parentCommentId | ID | false | request.body?.["parentCommentId"] | **postId** : **content** : **parentCommentId** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/comments** ```js axios({ method: 'POST', url: '/v1/comments', data: { postId:"ID", content:"Text", parentCommentId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "comment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "comment": { "id": "ID", "authorUserId": "ID", "postId": "ID", "content": "Text", "parentCommentId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Post` API Delete (soft-delete) a post. Only the author (or company admin for company posts) may delete. **Rest Route** The `deletePost` API REST controller can be triggered via the following route: `/v1/posts/:postId` **Rest Request Parameters** The `deletePost` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | postId | ID | true | request.params?.["postId"] | **postId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/posts/:postId** ```js axios({ method: 'DELETE', url: `/v1/posts/${postId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "post", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "post": { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Post` API Update content, visibility, or attachments of an existing post by its owner or company admin (if company post). **Rest Route** The `updatePost` API REST controller can be triggered via the following route: `/v1/posts/:postId` **Rest Request Parameters** The `updatePost` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | postId | ID | true | request.params?.["postId"] | | content | Text | false | request.body?.["content"] | | companyId | ID | false | request.body?.["companyId"] | | visibility | Enum | false | request.body?.["visibility"] | | attachmentUrls | String | false | request.body?.["attachmentUrls"] | **postId** : This id paremeter is used to select the required data object that will be updated **content** : **companyId** : **visibility** : **attachmentUrls** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/posts/:postId** ```js axios({ method: 'PATCH', url: `/v1/posts/${postId}`, data: { content:"Text", companyId:"ID", visibility:"Enum", attachmentUrls:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "post", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "post": { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Likes` API List likes on a given post (or by user). Supports filtering by postId and userId. **Rest Route** The `listLikes` API REST controller can be triggered via the following route: `/v1/likes` **Rest Request Parameters** **Filter Parameters** The `listLikes` api supports 2 optional filter parameters for filtering list results: **postId** (`ID`): Filter by postId - Single: `?postId=` - Multiple: `?postId=&postId=` - Null: `?postId=null` **userId** (`ID`): Filter by userId - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/likes** ```js axios({ method: 'GET', url: '/v1/likes', data: { }, params: { // Filter parameters (see Filter Parameters section above) // postId: '' // Filter by postId // userId: '' // Filter by userId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "likes", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "likes": [ { "id": "ID", "likedAt": "Date", "postId": "ID", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Unlike Post` API Undo a like by user for a given post. Soft-deletes the like record. **Rest Route** The `unlikePost` API REST controller can be triggered via the following route: `/v1/unlikepost/:likeId` **Rest Request Parameters** The `unlikePost` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | likeId | ID | true | request.params?.["likeId"] | **likeId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/unlikepost/:likeId** ```js axios({ method: 'DELETE', url: `/v1/unlikepost/${likeId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "like", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "like": { "id": "ID", "likedAt": "Date", "postId": "ID", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Comments` API List comments for a post (or by parentComment). Supports filtering by postId and parentCommentId. Sorted by creation date ascending. **Rest Route** The `listComments` API REST controller can be triggered via the following route: `/v1/comments` **Rest Request Parameters** **Filter Parameters** The `listComments` api supports 1 optional filter parameter for filtering list results: **postId** (`ID`): Filter by postId - Single: `?postId=` - Multiple: `?postId=&postId=` - Null: `?postId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/comments** ```js axios({ method: 'GET', url: '/v1/comments', data: { }, params: { // Filter parameters (see Filter Parameters section above) // postId: '' // Filter by postId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "comments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "comments": [ { "id": "ID", "authorUserId": "ID", "postId": "ID", "content": "Text", "parentCommentId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Comment` API Get a comment by ID. Any user can read comments. Soft-deleted comments not listed unless owner. **Rest Route** The `getComment` API REST controller can be triggered via the following route: `/v1/comments/:commentId` **Rest Request Parameters** The `getComment` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | commentId | ID | true | request.params?.["commentId"] | **commentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/comments/:commentId** ```js axios({ method: 'GET', url: `/v1/comments/${commentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "comment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "comment": { "id": "ID", "authorUserId": "ID", "postId": "ID", "content": "Text", "parentCommentId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Userposts` API list all posts of a user **Rest Route** The `listUserPosts` API REST controller can be triggered via the following route: `/v1/userposts` **Rest Request Parameters** **Filter Parameters** The `listUserPosts` api supports 3 optional filter parameters for filtering list results: **companyId** (`ID`): Filter by companyId - Single: `?companyId=` - Multiple: `?companyId=&companyId=` - Null: `?companyId=null` **authorUserId** (`ID`): Filter by authorUserId - Single: `?authorUserId=` - Multiple: `?authorUserId=&authorUserId=` - Null: `?authorUserId=null` **visibility** (`Enum`): Filter by visibility - Single: `?visibility=` (case-insensitive) - Multiple: `?visibility=&visibility=` - Null: `?visibility=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userposts** ```js axios({ method: 'GET', url: '/v1/userposts', data: { }, params: { // Filter parameters (see Filter Parameters section above) // companyId: '' // Filter by companyId // authorUserId: '' // Filter by authorUserId // visibility: '' // Filter by visibility } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "posts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "posts": [ { "id": "ID", "content": "Text", "companyId": "ID", "authorUserId": "ID", "visibility": "Enum", "visibility_idx": "Integer", "attachmentUrls": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Comment` API Delete (soft-delete) a comment. Only the author may delete. **Rest Route** The `deleteComment` API REST controller can be triggered via the following route: `/v1/comments/:commentId` **Rest Request Parameters** The `deleteComment` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | commentId | ID | true | request.params?.["commentId"] | **commentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/comments/:commentId** ```js axios({ method: 'DELETE', url: `/v1/comments/${commentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "comment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "comment": { "id": "ID", "authorUserId": "ID", "postId": "ID", "content": "Text", "parentCommentId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 11 - Messaging Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of messaging ## Service Access Messaging service management is handled through service specific base urls. Messaging service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the messaging service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/messaging-api` * **Staging:** `https://linkedin-stage.mindbricks.co/messaging-api` * **Production:** `https://linkedin.mindbricks.co/messaging-api` ## Scope **Messaging Service Description** Handles direct, private 1:1 and group messaging between users, conversation management, and message history/storage.. Messaging service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`message` Data Object**: Message posted within a conversation. Tracks content, sender, readBy, and deletedFor status per user. **`conversation` Data Object**: Messaging thread among users supporting 1:1 and group. Tracks participants, group status, and last message time. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Message Data Object Message posted within a conversation. Tracks content, sender, readBy, and deletedFor status per user. ### Message Data Object Properties Message data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `content` | Text | false | Yes | No | - | | `senderUserId` | ID | false | Yes | No | - | | `deletedFor` | ID | true | No | No | - | | `readBy` | ID | true | No | No | - | | `conversationId` | ID | false | Yes | No | - | | `sentAt` | Date | false | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `deletedFor` `readBy` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Relation Properties `senderUserId` `deletedFor` `readBy` `conversationId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **senderUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **deletedFor**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **readBy**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **conversationId**: ID Relation to `conversation`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `senderUserId` `conversationId` `sentAt` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **senderUserId**: ID has a filter named `senderUserId` - **conversationId**: ID has a filter named `conversationId` - **sentAt**: Date has a filter named `sentAt` ## Conversation Data Object Messaging thread among users supporting 1:1 and group. Tracks participants, group status, and last message time. ### Conversation Data Object Properties Conversation data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `isGroup` | Boolean | false | Yes | No | - | | `participantIds` | ID | true | Yes | No | - | | `lastMessageAt` | Date | false | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `participantIds` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Relation Properties `participantIds` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **participantIds**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `isGroup` `participantIds` `lastMessageAt` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **isGroup**: Boolean has a filter named `isGroup` - **participantIds**: ID has a filter named `participantIds` - **lastMessageAt**: Date has a filter named `lastMessageAt` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### Message Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createMessage` | `/v1/messages` | Auto | | Update | `updateMessage` | `/v1/messages/:messageId` | Auto | | Delete | `deleteMessage` | `/v1/messages/:messageId` | Auto | | Get | `getMessage` | `/v1/messages/:messageId` | Auto | | List | `listMessages` | `/v1/messages` | Auto | ### Conversation Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createConversation` | `/v1/conversations` | Auto | | Update | `updateConversation` | `/v1/conversations/:conversationId` | Auto | | Delete | `deleteConversation` | `/v1/conversations/:conversationId` | Auto | | Get | `getConversation` | `/v1/conversations/:conversationId` | Auto | | List | `listConversations` | `/v1/conversations` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `List Messages` API List messages in a conversation, ordered by sentAt ascending. Only participants can view. Support filters such as min/max sentAt, unreadBy, etc. **Rest Route** The `listMessages` API REST controller can be triggered via the following route: `/v1/messages` **Rest Request Parameters** **Filter Parameters** The `listMessages` api supports 3 optional filter parameters for filtering list results: **senderUserId** (`ID`): Filter by senderUserId - Single: `?senderUserId=` - Multiple: `?senderUserId=&senderUserId=` - Null: `?senderUserId=null` **conversationId** (`ID`): Filter by conversationId - Single: `?conversationId=` - Multiple: `?conversationId=&conversationId=` - Null: `?conversationId=null` **sentAt** (`Date`): Filter by sentAt - Single date: `?sentAt=2024-01-15` - Multiple dates: `?sentAt=2024-01-15&sentAt=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?sentAt=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messages** ```js axios({ method: 'GET', url: '/v1/messages', data: { }, params: { // Filter parameters (see Filter Parameters section above) // senderUserId: '' // Filter by senderUserId // conversationId: '' // Filter by conversationId // sentAt: '' // Filter by sentAt } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messages": [ { "id": "ID", "content": "Text", "senderUserId": "ID", "deletedFor": "ID", "readBy": "ID", "conversationId": "ID", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Conversation` API Update conversation (e.g., participants, group flag). Only group conversations can be updated. Only current participants can update. For group: can add/remove participants; 1:1 conversations can't change participantIds or isGroup. **Rest Route** The `updateConversation` API REST controller can be triggered via the following route: `/v1/conversations/:conversationId` **Rest Request Parameters** The `updateConversation` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | conversationId | ID | true | request.params?.["conversationId"] | | isGroup | Boolean | false | request.body?.["isGroup"] | | participantIds | ID | false | request.body?.["participantIds"] | | lastMessageAt | Date | false | request.body?.["lastMessageAt"] | **conversationId** : This id paremeter is used to select the required data object that will be updated **isGroup** : **participantIds** : **lastMessageAt** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/conversations/:conversationId** ```js axios({ method: 'PATCH', url: `/v1/conversations/${conversationId}`, data: { isGroup:"Boolean", participantIds:"ID", lastMessageAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "conversation", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "conversation": { "id": "ID", "isGroup": "Boolean", "participantIds": "ID", "lastMessageAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Message` API Fetch a specific message if the requesting user is a participant in the conversation. **Rest Route** The `getMessage` API REST controller can be triggered via the following route: `/v1/messages/:messageId` **Rest Request Parameters** The `getMessage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messageId | ID | true | request.params?.["messageId"] | **messageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messages/:messageId** ```js axios({ method: 'GET', url: `/v1/messages/${messageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "message", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "message": { "id": "ID", "content": "Text", "senderUserId": "ID", "deletedFor": "ID", "readBy": "ID", "conversationId": "ID", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Conversation` API Fetch details for a conversation thread. Only participants may view. **Rest Route** The `getConversation` API REST controller can be triggered via the following route: `/v1/conversations/:conversationId` **Rest Request Parameters** The `getConversation` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | conversationId | ID | true | request.params?.["conversationId"] | **conversationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/conversations/:conversationId** ```js axios({ method: 'GET', url: `/v1/conversations/${conversationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "conversation", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "conversation": { "id": "ID", "isGroup": "Boolean", "participantIds": "ID", "lastMessageAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Message` API Update content of a message or update readBy/deletedFor. Only sender may update content. Any participant can update their readBy/deletedFor entries. Content updates forbidden except for sender. **Rest Route** The `updateMessage` API REST controller can be triggered via the following route: `/v1/messages/:messageId` **Rest Request Parameters** The `updateMessage` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messageId | ID | true | request.params?.["messageId"] | | content | Text | false | request.body?.["content"] | | deletedFor | ID | false | request.body?.["deletedFor"] | | readBy | ID | false | request.body?.["readBy"] | **messageId** : This id paremeter is used to select the required data object that will be updated **content** : **deletedFor** : **readBy** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messages/:messageId** ```js axios({ method: 'PATCH', url: `/v1/messages/${messageId}`, data: { content:"Text", deletedFor:"ID", readBy:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "message", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "message": { "id": "ID", "content": "Text", "senderUserId": "ID", "deletedFor": "ID", "readBy": "ID", "conversationId": "ID", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Conversation` API Soft-delete a conversation thread. Only participants can delete. This is 'hide for all' (e.g., group exit or complete deletion). **Rest Route** The `deleteConversation` API REST controller can be triggered via the following route: `/v1/conversations/:conversationId` **Rest Request Parameters** The `deleteConversation` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | conversationId | ID | true | request.params?.["conversationId"] | **conversationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/conversations/:conversationId** ```js axios({ method: 'DELETE', url: `/v1/conversations/${conversationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "conversation", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "conversation": { "id": "ID", "isGroup": "Boolean", "participantIds": "ID", "lastMessageAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Conversations` API List all conversations for the session user (where session userId in participantIds). Shows recent first (lastMessageAt desc). **Rest Route** The `listConversations` API REST controller can be triggered via the following route: `/v1/conversations` **Rest Request Parameters** **Filter Parameters** The `listConversations` api supports 4 optional filter parameters for filtering list results: **isGroup** (`Boolean`): Filter by isGroup - True: `?isGroup=true` - False: `?isGroup=false` - Null: `?isGroup=null` **participantIds** (`ID` array): Filter by participantIds - Single: `?participantIds=` - Multiple: `?participantIds=&participantIds=` - Null: `?participantIds=null` - Array contains: `?participantIds=&participantIds_op=contains` (default) - Array overlap: `?participantIds=&participantIds=&participantIds_op=overlap` **participantIds_op** (`String`): Operator for filtering array property "participantIds". Use "contains" to check if array contains the value, or "overlap" to check if arrays have common elements. - Single (partial match, case-insensitive): `?participantIds_op=` - Multiple: `?participantIds_op=&participantIds_op=` - Null: `?participantIds_op=null` **lastMessageAt** (`Date`): Filter by lastMessageAt - Single date: `?lastMessageAt=2024-01-15` - Multiple dates: `?lastMessageAt=2024-01-15&lastMessageAt=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?lastMessageAt=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/conversations** ```js axios({ method: 'GET', url: '/v1/conversations', data: { }, params: { // Filter parameters (see Filter Parameters section above) // isGroup: '' // Filter by isGroup // participantIds: '' // Filter by participantIds // participantIds_op: '' // Filter by participantIds_op // lastMessageAt: '' // Filter by lastMessageAt } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "conversations", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "conversations": [ { "id": "ID", "isGroup": "Boolean", "participantIds": "ID", "lastMessageAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Message` API Soft-delete a message. Sender can hard-delete for all (set isActive=false). Any participant can soft-delete (add own userId to deletedFor array). **Rest Route** The `deleteMessage` API REST controller can be triggered via the following route: `/v1/messages/:messageId` **Rest Request Parameters** The `deleteMessage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messageId | ID | true | request.params?.["messageId"] | **messageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messages/:messageId** ```js axios({ method: 'DELETE', url: `/v1/messages/${messageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "message", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "message": { "id": "ID", "content": "Text", "senderUserId": "ID", "deletedFor": "ID", "readBy": "ID", "conversationId": "ID", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Message` API Send a new message in a conversation. Only participants can send. On send, update conversation.lastMessageAt and set sentAt=now, senderUserId=session user. Add sender to readBy by default. Publish event for notification subsystem. **Rest Route** The `createMessage` API REST controller can be triggered via the following route: `/v1/messages` **Rest Request Parameters** The `createMessage` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | content | Text | true | request.body?.["content"] | | senderUserId | ID | true | request.body?.["senderUserId"] | | deletedFor | ID | false | request.body?.["deletedFor"] | | readBy | ID | false | request.body?.["readBy"] | | conversationId | ID | true | request.body?.["conversationId"] | | sentAt | Date | false | request.body?.["sentAt"] | **content** : **senderUserId** : **deletedFor** : **readBy** : **conversationId** : **sentAt** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messages** ```js axios({ method: 'POST', url: '/v1/messages', data: { content:"Text", senderUserId:"ID", deletedFor:"ID", readBy:"ID", conversationId:"ID", sentAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "message", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "message": { "id": "ID", "content": "Text", "senderUserId": "ID", "deletedFor": "ID", "readBy": "ID", "conversationId": "ID", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Conversation` API Create a new conversation (thread) for messaging; can be group (isGroup) or 1:1. Participants must include the session user. For 1:1, only two users allowed; for group, at least three. If 1:1 exists, prevent duplicate. **Rest Route** The `createConversation` API REST controller can be triggered via the following route: `/v1/conversations` **Rest Request Parameters** The `createConversation` api has got 3 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | isGroup | Boolean | true | request.body?.["isGroup"] | | participantIds | ID | true | request.body?.["participantIds"] | | lastMessageAt | Date | false | request.body?.["lastMessageAt"] | **isGroup** : **participantIds** : **lastMessageAt** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/conversations** ```js axios({ method: 'POST', url: '/v1/conversations', data: { isGroup:"Boolean", participantIds:"ID", lastMessageAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "conversation", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "conversation": { "id": "ID", "isGroup": "Boolean", "participantIds": "ID", "lastMessageAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 12 - Profile Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of profile ## Service Access Profile service management is handled through service specific base urls. Profile service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the profile service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/profile-api` * **Staging:** `https://linkedin-stage.mindbricks.co/profile-api` * **Production:** `https://linkedin.mindbricks.co/profile-api` ## Scope **Profile Service Description** Handles user professional profiles, including experience, education, skills, languages, certifications, profile photo, and visibility controls. Enables recruiter search, elastic-style indexing, and profile editing, with all data linked to authenticated users.. Profile service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`profile` Data Object**: Professional profile for a user, includes core info and arrays of experience/education/skills. One profile per user... **`premiumsubscription` Data Object**: premium subscription for a user **`certification` Data Object**: Official certification available for selection in user profile (dictionary only, not user relation). **`language` Data Object**: Official language available for selection in user profile (dictionary only, not user relation). **`sys_premiumsubscriptionPayment` Data Object**: A payment storage object to store the payment life cyle of orders based on premiumsubscription object. It is autocreated based on the source object's checkout config **`sys_paymentCustomer` Data Object**: A payment storage object to store the customer values of the payment platform **`sys_paymentMethod` Data Object**: A payment storage object to store the payment methods of the platform customers ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Profile Data Object Professional profile for a user, includes core info and arrays of experience/education/skills. One profile per user... ### Profile Data Object Properties Profile data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `summary` | Text | false | No | No | - | | `headline` | String | false | No | No | - | | `profilePhotoUrl` | String | false | No | No | - | | `userId` | ID | false | Yes | No | - | | `fullName` | String | false | Yes | No | - | | `currentCompany` | String | false | No | No | - | | `industry` | String | false | No | No | - | | `languages` | String | true | No | No | - | | `skills` | String | true | No | No | - | | `location` | String | false | No | No | - | | `experience` | Object | true | No | No | - | | `profileVisibility` | Enum | false | Yes | No | - | | `education` | Object | true | No | No | - | | `certifications` | String | true | No | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `languages` `skills` `experience` `education` `certifications` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **profileVisibility**: [public, private] ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `headline` `fullName` `currentCompany` `industry` `location` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **headline**: String has a filter named `headline` - **fullName**: String has a filter named `fullName` - **currentCompany**: String has a filter named `currentCompany` - **industry**: String has a filter named `industry` - **location**: String has a filter named `location` ## Premiumsubscription Data Object premium subscription for a user ### Premiumsubscription Data Object Properties Premiumsubscription data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `profileId` | ID | false | Yes | No | - | | `currency` | String | false | Yes | No | - | | `status` | String | false | Yes | No | - | | `price` | Double | false | Yes | No | - | | `userId` | ID | false | Yes | No | - | | `paymentConfirmation` | Enum | false | Yes | No | An automatic property that is used to check the confirmed status of the payment set by webhooks. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **paymentConfirmation**: [pending, processing, paid, canceled] ### Relation Properties `profileId` `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **profileId**: ID Relation to `profile`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `profileId` `currency` `status` `price` `userId` `paymentConfirmation` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **profileId**: ID has a filter named `subscriptionProfileId` - **currency**: String has a filter named `subscriptionCurrency` - **status**: String has a filter named `subscriptionStatus` - **price**: Double has a filter named `subscriptionPrice` - **userId**: ID has a filter named `subscriptionUserId` - **paymentConfirmation**: Enum has a filter named `paymentConfirmation` ## Certification Data Object Official certification available for selection in user profile (dictionary only, not user relation). ### Certification Data Object Properties Certification data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `name` | String | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `name` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **name**: String has a filter named `name` ## Language Data Object Official language available for selection in user profile (dictionary only, not user relation). ### Language Data Object Properties Language data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `name` | String | false | Yes | No | - | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `name` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **name**: String has a filter named `name` ## Sys_premiumsubscriptionPayment Data Object A payment storage object to store the payment life cyle of orders based on premiumsubscription object. It is autocreated based on the source object's checkout config ### Sys_premiumsubscriptionPayment Data Object Properties Sys_premiumsubscriptionPayment data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `ownerId` | ID | false | No | No | An ID value to represent owner user who created the order | | `orderId` | ID | false | Yes | No | an ID value to represent the orderId which is the ID parameter of the source premiumsubscription object | | `paymentId` | String | false | Yes | No | A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type | | `paymentStatus` | String | false | Yes | No | A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. | | `statusLiteral` | String | false | Yes | No | A string value to represent the logical payment status which belongs to the application lifecycle itself. | | `redirectUrl` | String | false | No | No | A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **ownerId**: ID has a filter named `ownerId` - **orderId**: ID has a filter named `orderId` - **paymentId**: String has a filter named `paymentId` - **paymentStatus**: String has a filter named `paymentStatus` - **statusLiteral**: String has a filter named `statusLiteral` - **redirectUrl**: String has a filter named `redirectUrl` ## Sys_paymentCustomer Data Object A payment storage object to store the customer values of the payment platform ### Sys_paymentCustomer Data Object Properties Sys_paymentCustomer data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `userId` | ID | false | No | No | An ID value to represent the user who is created as a stripe customer | | `customerId` | String | false | Yes | No | A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway | | `platform` | String | false | Yes | No | A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `userId` `customerId` `platform` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **platform**: String has a filter named `platform` ## Sys_paymentMethod Data Object A payment storage object to store the payment methods of the platform customers ### Sys_paymentMethod Data Object Properties Sys_paymentMethod data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `paymentMethodId` | String | false | Yes | No | A string value to represent the id of the payment method on the payment platform. | | `userId` | ID | false | Yes | No | An ID value to represent the user who owns the payment method | | `customerId` | String | false | Yes | No | A string value to represent the customer id which is generated on the payment gateway. | | `cardHolderName` | String | false | No | No | A string value to represent the name of the card holder. It can be different than the registered customer. | | `cardHolderZip` | String | false | No | No | A string value to represent the zip code of the card holder. It is used for address verification in specific countries. | | `platform` | String | false | Yes | No | A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | | `cardInfo` | Object | false | Yes | No | A Json value to store the card details of the payment method. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` `cardInfo` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **paymentMethodId**: String has a filter named `paymentMethodId` - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **cardHolderName**: String has a filter named `cardHolderName` - **cardHolderZip**: String has a filter named `cardHolderZip` - **platform**: String has a filter named `platform` - **cardInfo**: Object has a filter named `cardInfo` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### Profile Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createProfile` | `/v1/profiles` | Auto | | Update | `updateProfile` | `/v1/profiles/:profileId` | Auto | | Delete | `deleteProfile` | `/v1/profiles/:profileId` | Auto | | Get | `getProfile` | `/v1/profiles/:profileId` | Auto | | List | `listProfiles` | `/v1/profiles` | Auto | ### Premiumsubscription Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createPremuimSub` | `/v1/premuimsub` | Auto | | Update | `updatePremuimSub` | `/v1/premuimsub/:premiumsubscriptionId` | Auto | | Delete | `deletePremuimSub` | `/v1/premuimsub/:premiumsubscriptionId` | Auto | | Get | `getPremuimSub` | `/v1/premuimsub/:premiumsubscriptionId` | Auto | | List | `listPremuimSub` | `/v1/premuimsub` | Auto | ### Certification Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createCertification` | `/v1/certifications` | Auto | | Update | `updateCertification` | `/v1/certifications/:certificationId` | Auto | | Delete | `deleteCertification` | `/v1/certifications/:certificationId` | Auto | | Get | `getCertification` | `/v1/certifications/:certificationId` | Auto | | List | `listCertifications` | `/v1/certifications` | Auto | ### Language Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createLanguage` | `/v1/languages` | Auto | | Update | `updateLanguage` | `/v1/languages/:languageId` | Auto | | Delete | `deleteLanguage` | `/v1/languages/:languageId` | Auto | | Get | `getLanguage` | `/v1/languages/:languageId` | Auto | | List | `listLanguages` | `/v1/languages` | Auto | ### Sys_premiumsubscriptionPayment Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createPremiumsubscriptionPayment` | `/v1/premiumsubscriptionpayment` | Auto | | Update | `updatePremiumsubscriptionPayment` | `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` | Auto | | Delete | `deletePremiumsubscriptionPayment` | `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` | Auto | | Get | `getPremiumsubscriptionPayment` | `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` | Auto | | List | `listPremiumsubscriptionPayments` | `/v1/premiumsubscriptionpayments` | Auto | ### Sys_paymentCustomer Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | `getPaymentCustomerByUserId` | `/v1/paymentcustomers/:userId` | Auto | | List | `listPaymentCustomers` | `/v1/paymentcustomers` | Auto | ### Sys_paymentMethod Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | _none_ | - | Auto | | List | `listPaymentCustomerMethods` | `/v1/paymentcustomermethods/:userId` | Auto | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Update Profile` API Updates the profile of the authenticated user. Includes visibility settings, skills, experience, etc. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profiles/:profileId` **Rest Request Parameters** The `updateProfile` api has got 14 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | profileId | ID | true | request.params?.["profileId"] | | summary | Text | false | request.body?.["summary"] | | headline | String | false | request.body?.["headline"] | | profilePhotoUrl | String | false | request.body?.["profilePhotoUrl"] | | fullName | String | false | request.body?.["fullName"] | | currentCompany | String | false | request.body?.["currentCompany"] | | industry | String | false | request.body?.["industry"] | | languages | String | false | request.body?.["languages"] | | skills | String | false | request.body?.["skills"] | | location | String | false | request.body?.["location"] | | experience | Object | false | request.body?.["experience"] | | profileVisibility | Enum | true | request.body?.["profileVisibility"] | | education | Object | false | request.body?.["education"] | | certifications | String | false | request.body?.["certifications"] | **profileId** : This id paremeter is used to select the required data object that will be updated **summary** : **headline** : **profilePhotoUrl** : **fullName** : **currentCompany** : **industry** : **languages** : **skills** : **location** : **experience** : **profileVisibility** : **education** : **certifications** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profiles/:profileId** ```js axios({ method: 'PATCH', url: `/v1/profiles/${profileId}`, data: { summary:"Text", headline:"String", profilePhotoUrl:"String", fullName:"String", currentCompany:"String", industry:"String", languages:"String", skills:"String", location:"String", experience:"Object", profileVisibility:"Enum", education:"Object", certifications:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "profile", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "profile": { "id": "ID", "summary": "Text", "headline": "String", "profilePhotoUrl": "String", "userId": "ID", "fullName": "String", "currentCompany": "String", "industry": "String", "languages": "String", "skills": "String", "location": "String", "experience": "Object", "profileVisibility": "Enum", "profileVisibility_idx": "Integer", "education": "Object", "certifications": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Profile` API Deletes the profile of the authenticated user (soft delete). **Rest Route** The `deleteProfile` API REST controller can be triggered via the following route: `/v1/profiles/:profileId` **Rest Request Parameters** The `deleteProfile` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | profileId | ID | true | request.params?.["profileId"] | **profileId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/profiles/:profileId** ```js axios({ method: 'DELETE', url: `/v1/profiles/${profileId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "profile", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "profile": { "id": "ID", "summary": "Text", "headline": "String", "profilePhotoUrl": "String", "userId": "ID", "fullName": "String", "currentCompany": "String", "industry": "String", "languages": "String", "skills": "String", "location": "String", "experience": "Object", "profileVisibility": "Enum", "profileVisibility_idx": "Integer", "education": "Object", "certifications": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Language` API Deletes a language entry from the dictionary. **Rest Route** The `deleteLanguage` API REST controller can be triggered via the following route: `/v1/languages/:languageId` **Rest Request Parameters** The `deleteLanguage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | languageId | ID | true | request.params?.["languageId"] | **languageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/languages/:languageId** ```js axios({ method: 'DELETE', url: `/v1/languages/${languageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "language", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "language": { "id": "ID", "name": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Language` API Edit an existing language entry. **Rest Route** The `updateLanguage` API REST controller can be triggered via the following route: `/v1/languages/:languageId` **Rest Request Parameters** The `updateLanguage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | languageId | ID | true | request.params?.["languageId"] | **languageId** : This id paremeter is used to select the required data object that will be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/languages/:languageId** ```js axios({ method: 'PATCH', url: `/v1/languages/${languageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "language", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "language": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Profiles` API Lists profiles by search/filter. Only public profiles are listed, unless the current user is the owner. **Rest Route** The `listProfiles` API REST controller can be triggered via the following route: `/v1/profiles` **Rest Request Parameters** **Filter Parameters** The `listProfiles` api supports 5 optional filter parameters for filtering list results: **headline** (`String`): Filter by headline - Single (partial match, case-insensitive): `?headline=` - Multiple: `?headline=&headline=` - Null: `?headline=null` **fullName** (`String`): Filter by fullName - Single (partial match, case-insensitive): `?fullName=` - Multiple: `?fullName=&fullName=` - Null: `?fullName=null` **currentCompany** (`String`): Filter by currentCompany - Single (partial match, case-insensitive): `?currentCompany=` - Multiple: `?currentCompany=¤tCompany=` - Null: `?currentCompany=null` **industry** (`String`): Filter by industry - Single (partial match, case-insensitive): `?industry=` - Multiple: `?industry=&industry=` - Null: `?industry=null` **location** (`String`): Filter by location - Single (partial match, case-insensitive): `?location=` - Multiple: `?location=&location=` - Null: `?location=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/profiles** ```js axios({ method: 'GET', url: '/v1/profiles', data: { }, params: { // Filter parameters (see Filter Parameters section above) // headline: '' // Filter by headline // fullName: '' // Filter by fullName // currentCompany: '' // Filter by currentCompany // industry: '' // Filter by industry // location: '' // Filter by location } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "profiles", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "profiles": [ { "id": "ID", "summary": "Text", "headline": "String", "profilePhotoUrl": "String", "userId": "ID", "fullName": "String", "currentCompany": "String", "industry": "String", "languages": "String", "skills": "String", "location": "String", "experience": "Object", "profileVisibility": "Enum", "profileVisibility_idx": "Integer", "education": "Object", "certifications": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Languages` API Lists all available languages for profile selection. **Rest Route** The `listLanguages` API REST controller can be triggered via the following route: `/v1/languages` **Rest Request Parameters** **Filter Parameters** The `listLanguages` api supports 1 optional filter parameter for filtering list results: **name** (`String`): Filter by name - Single (partial match, case-insensitive): `?name=` - Multiple: `?name=&name=` - Null: `?name=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/languages** ```js axios({ method: 'GET', url: '/v1/languages', data: { }, params: { // Filter parameters (see Filter Parameters section above) // name: '' // Filter by name } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "languages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "languages": [ { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Language` API Retrieves a language entry by ID. **Rest Route** The `getLanguage` API REST controller can be triggered via the following route: `/v1/languages/:languageId` **Rest Request Parameters** The `getLanguage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | languageId | ID | true | request.params?.["languageId"] | **languageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/languages/:languageId** ```js axios({ method: 'GET', url: `/v1/languages/${languageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "language", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "language": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Language` API Add a new language to the dictionary for user profiles. Must be unique by name. **Rest Route** The `createLanguage` API REST controller can be triggered via the following route: `/v1/languages` **Rest Request Parameters** The `createLanguage` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.["name"] | **name** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/languages** ```js axios({ method: 'POST', url: '/v1/languages', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "language", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "language": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Profile` API Creates a new professional profile for the authenticated user. Each user can create only one profile. **Rest Route** The `createProfile` API REST controller can be triggered via the following route: `/v1/profiles` **Rest Request Parameters** The `createProfile` api has got 13 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | summary | Text | false | request.body?.["summary"] | | headline | String | false | request.body?.["headline"] | | profilePhotoUrl | String | false | request.body?.["profilePhotoUrl"] | | fullName | String | true | request.body?.["fullName"] | | currentCompany | String | false | request.body?.["currentCompany"] | | industry | String | false | request.body?.["industry"] | | languages | String | false | request.body?.["languages"] | | skills | String | false | request.body?.["skills"] | | location | String | false | request.body?.["location"] | | experience | Object | false | request.body?.["experience"] | | profileVisibility | Enum | true | request.body?.["profileVisibility"] | | education | Object | false | request.body?.["education"] | | certifications | String | false | request.body?.["certifications"] | **summary** : **headline** : **profilePhotoUrl** : **fullName** : **currentCompany** : **industry** : **languages** : **skills** : **location** : **experience** : **profileVisibility** : **education** : **certifications** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/profiles** ```js axios({ method: 'POST', url: '/v1/profiles', data: { summary:"Text", headline:"String", profilePhotoUrl:"String", fullName:"String", currentCompany:"String", industry:"String", languages:"String", skills:"String", location:"String", experience:"Object", profileVisibility:"Enum", education:"Object", certifications:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "profile", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "profile": { "id": "ID", "summary": "Text", "headline": "String", "profilePhotoUrl": "String", "userId": "ID", "fullName": "String", "currentCompany": "String", "industry": "String", "languages": "String", "skills": "String", "location": "String", "experience": "Object", "profileVisibility": "Enum", "profileVisibility_idx": "Integer", "education": "Object", "certifications": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Profile` API Retrieves a user profile by ID. If private, only the owner can get; if public, anyone can view. **Rest Route** The `getProfile` API REST controller can be triggered via the following route: `/v1/profiles/:profileId` **Rest Request Parameters** The `getProfile` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | profileId | ID | true | request.params?.["profileId"] | **profileId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/profiles/:profileId** ```js axios({ method: 'GET', url: `/v1/profiles/${profileId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "profile", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "profile": { "id": "ID", "summary": "Text", "headline": "String", "profilePhotoUrl": "String", "userId": "ID", "fullName": "String", "currentCompany": "String", "industry": "String", "languages": "String", "skills": "String", "location": "String", "experience": "Object", "profileVisibility": "Enum", "profileVisibility_idx": "Integer", "education": "Object", "certifications": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Premuimsub` API **Rest Route** The `deletePremuimSub` API REST controller can be triggered via the following route: `/v1/premuimsub/:premiumsubscriptionId` **Rest Request Parameters** The `deletePremuimSub` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | **premiumsubscriptionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/premuimsub/:premiumsubscriptionId** ```js axios({ method: 'DELETE', url: `/v1/premuimsub/${premiumsubscriptionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Certification` API Edit an existing certification entry. **Rest Route** The `updateCertification` API REST controller can be triggered via the following route: `/v1/certifications/:certificationId` **Rest Request Parameters** The `updateCertification` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | certificationId | ID | true | request.params?.["certificationId"] | **certificationId** : This id paremeter is used to select the required data object that will be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/certifications/:certificationId** ```js axios({ method: 'PATCH', url: `/v1/certifications/${certificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "certification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "certification": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Premuimsub` API **Rest Route** The `createPremuimSub` API REST controller can be triggered via the following route: `/v1/premuimsub` **Rest Request Parameters** The `createPremuimSub` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | profileId | ID | true | request.body?.["profileId"] | | currency | String | true | request.body?.["currency"] | | status | String | true | request.body?.["status"] | | price | Double | true | request.body?.["price"] | | userId | ID | true | request.body?.["userId"] | **profileId** : **currency** : **status** : **price** : **userId** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/premuimsub** ```js axios({ method: 'POST', url: '/v1/premuimsub', data: { profileId:"ID", currency:"String", status:"String", price:"Double", userId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Certifications` API Lists all available certifications for profile selection/display. **Rest Route** The `listCertifications` API REST controller can be triggered via the following route: `/v1/certifications` **Rest Request Parameters** **Filter Parameters** The `listCertifications` api supports 1 optional filter parameter for filtering list results: **name** (`String`): Filter by name - Single (partial match, case-insensitive): `?name=` - Multiple: `?name=&name=` - Null: `?name=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/certifications** ```js axios({ method: 'GET', url: '/v1/certifications', data: { }, params: { // Filter parameters (see Filter Parameters section above) // name: '' // Filter by name } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "certifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "certifications": [ { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Premuimsub` API **Rest Route** The `updatePremuimSub` API REST controller can be triggered via the following route: `/v1/premuimsub/:premiumsubscriptionId` **Rest Request Parameters** The `updatePremuimSub` api has got 6 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | | profileId | ID | false | request.body?.["profileId"] | | currency | String | false | request.body?.["currency"] | | status | String | false | request.body?.["status"] | | price | Double | false | request.body?.["price"] | | userId | ID | false | request.body?.["userId"] | **premiumsubscriptionId** : This id paremeter is used to select the required data object that will be updated **profileId** : **currency** : **status** : **price** : **userId** : **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/premuimsub/:premiumsubscriptionId** ```js axios({ method: 'PATCH', url: `/v1/premuimsub/${premiumsubscriptionId}`, data: { profileId:"ID", currency:"String", status:"String", price:"Double", userId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Premuimsub` API **Rest Route** The `getPremuimSub` API REST controller can be triggered via the following route: `/v1/premuimsub/:premiumsubscriptionId` **Rest Request Parameters** The `getPremuimSub` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | **premiumsubscriptionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premuimsub/:premiumsubscriptionId** ```js axios({ method: 'GET', url: `/v1/premuimsub/${premiumsubscriptionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Certification` API Add a new certification for user profiles. Must be unique by name. **Rest Route** The `createCertification` API REST controller can be triggered via the following route: `/v1/certifications` **Rest Request Parameters** The `createCertification` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.["name"] | **name** : **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/certifications** ```js axios({ method: 'POST', url: '/v1/certifications', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "certification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "certification": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Certification` API Retrieves a certification entry by ID. **Rest Route** The `getCertification` API REST controller can be triggered via the following route: `/v1/certifications/:certificationId` **Rest Request Parameters** The `getCertification` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | certificationId | ID | true | request.params?.["certificationId"] | **certificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/certifications/:certificationId** ```js axios({ method: 'GET', url: `/v1/certifications/${certificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "certification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "certification": { "id": "ID", "name": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Premuimsub` API **Rest Route** The `listPremuimSub` API REST controller can be triggered via the following route: `/v1/premuimsub` **Rest Request Parameters** **Filter Parameters** The `listPremuimSub` api supports 6 optional filter parameters for filtering list results: **subscriptionProfileId** (`ID`): Filter by subscriptionProfileId - Single: `?subscriptionProfileId=` - Multiple: `?subscriptionProfileId=&subscriptionProfileId=` - Null: `?subscriptionProfileId=null` **subscriptionCurrency** (`String`): Filter by subscriptionCurrency - Single (partial match, case-insensitive): `?subscriptionCurrency=` - Multiple: `?subscriptionCurrency=&subscriptionCurrency=` - Null: `?subscriptionCurrency=null` **subscriptionStatus** (`String`): Filter by subscriptionStatus - Single (partial match, case-insensitive): `?subscriptionStatus=` - Multiple: `?subscriptionStatus=&subscriptionStatus=` - Null: `?subscriptionStatus=null` **subscriptionPrice** (`Double`): Filter by subscriptionPrice - Single: `?subscriptionPrice=` - Multiple: `?subscriptionPrice=&subscriptionPrice=` - Range: `?subscriptionPrice=$lt-`, `$lte-`, `$gt-`, `$gte-`, `$btw--` - Null: `?subscriptionPrice=null` **subscriptionUserId** (`ID`): Filter by subscriptionUserId - Single: `?subscriptionUserId=` - Multiple: `?subscriptionUserId=&subscriptionUserId=` - Null: `?subscriptionUserId=null` **paymentConfirmation** (`Enum`): An automatic property that is used to check the confirmed status of the payment set by webhooks. - Single: `?paymentConfirmation=` (case-insensitive) - Multiple: `?paymentConfirmation=&paymentConfirmation=` - Null: `?paymentConfirmation=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premuimsub** ```js axios({ method: 'GET', url: '/v1/premuimsub', data: { }, params: { // Filter parameters (see Filter Parameters section above) // subscriptionProfileId: '' // Filter by subscriptionProfileId // subscriptionCurrency: '' // Filter by subscriptionCurrency // subscriptionStatus: '' // Filter by subscriptionStatus // subscriptionPrice: '' // Filter by subscriptionPrice // subscriptionUserId: '' // Filter by subscriptionUserId // paymentConfirmation: '' // Filter by paymentConfirmation } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscriptions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "premiumsubscriptions": [ { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Certification` API Deletes a certification entry from the dictionary. **Rest Route** The `deleteCertification` API REST controller can be triggered via the following route: `/v1/certifications/:certificationId` **Rest Request Parameters** The `deleteCertification` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | certificationId | ID | true | request.params?.["certificationId"] | **certificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/certifications/:certificationId** ```js axios({ method: 'DELETE', url: `/v1/certifications/${certificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "certification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "certification": { "id": "ID", "name": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Premiumsubscriptionpayment` API This route is used to get the payment information by ID. **Rest Route** The `getPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` **Rest Request Parameters** The `getPremiumsubscriptionPayment` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_premiumsubscriptionPaymentId | ID | true | request.params?.["sys_premiumsubscriptionPaymentId"] | **sys_premiumsubscriptionPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId** ```js axios({ method: 'GET', url: `/v1/premiumsubscriptionpayment/${sys_premiumsubscriptionPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Premiumsubscriptionpayments` API This route is used to list all payments. **Rest Route** The `listPremiumsubscriptionPayments` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpayments` **Rest Request Parameters** **Filter Parameters** The `listPremiumsubscriptionPayments` api supports 6 optional filter parameters for filtering list results: **ownerId** (`ID`): An ID value to represent owner user who created the order - Single: `?ownerId=` - Multiple: `?ownerId=&ownerId=` - Null: `?ownerId=null` **orderId** (`ID`): an ID value to represent the orderId which is the ID parameter of the source premiumsubscription object - Single: `?orderId=` - Multiple: `?orderId=&orderId=` - Null: `?orderId=null` **paymentId** (`String`): A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type - Single (partial match, case-insensitive): `?paymentId=` - Multiple: `?paymentId=&paymentId=` - Null: `?paymentId=null` **paymentStatus** (`String`): A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. - Single (partial match, case-insensitive): `?paymentStatus=` - Multiple: `?paymentStatus=&paymentStatus=` - Null: `?paymentStatus=null` **statusLiteral** (`String`): A string value to represent the logical payment status which belongs to the application lifecycle itself. - Single (partial match, case-insensitive): `?statusLiteral=` - Multiple: `?statusLiteral=&statusLiteral=` - Null: `?statusLiteral=null` **redirectUrl** (`String`): A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. - Single (partial match, case-insensitive): `?redirectUrl=` - Multiple: `?redirectUrl=&redirectUrl=` - Null: `?redirectUrl=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premiumsubscriptionpayments** ```js axios({ method: 'GET', url: '/v1/premiumsubscriptionpayments', data: { }, params: { // Filter parameters (see Filter Parameters section above) // ownerId: '' // Filter by ownerId // orderId: '' // Filter by orderId // paymentId: '' // Filter by paymentId // paymentStatus: '' // Filter by paymentStatus // statusLiteral: '' // Filter by statusLiteral // redirectUrl: '' // Filter by redirectUrl } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_premiumsubscriptionPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Premiumsubscriptionpayment` API This route is used to create a new payment. **Rest Route** The `createPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpayment` **Rest Request Parameters** The `createPremiumsubscriptionPayment` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.["orderId"] | | paymentId | String | true | request.body?.["paymentId"] | | paymentStatus | String | true | request.body?.["paymentStatus"] | | statusLiteral | String | true | request.body?.["statusLiteral"] | | redirectUrl | String | false | request.body?.["redirectUrl"] | **orderId** : an ID value to represent the orderId which is the ID parameter of the source premiumsubscription object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/premiumsubscriptionpayment** ```js axios({ method: 'POST', url: '/v1/premiumsubscriptionpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Premiumsubscriptionpayment` API This route is used to update an existing payment. **Rest Route** The `updatePremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` **Rest Request Parameters** The `updatePremiumsubscriptionPayment` api has got 5 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_premiumsubscriptionPaymentId | ID | true | request.params?.["sys_premiumsubscriptionPaymentId"] | | paymentId | String | false | request.body?.["paymentId"] | | paymentStatus | String | false | request.body?.["paymentStatus"] | | statusLiteral | String | false | request.body?.["statusLiteral"] | | redirectUrl | String | false | request.body?.["redirectUrl"] | **sys_premiumsubscriptionPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId** ```js axios({ method: 'PATCH', url: `/v1/premiumsubscriptionpayment/${sys_premiumsubscriptionPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Premiumsubscriptionpayment` API This route is used to delete a payment. **Rest Route** The `deletePremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId` **Rest Request Parameters** The `deletePremiumsubscriptionPayment` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_premiumsubscriptionPaymentId | ID | true | request.params?.["sys_premiumsubscriptionPaymentId"] | **sys_premiumsubscriptionPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/premiumsubscriptionpayment/:sys_premiumsubscriptionPaymentId** ```js axios({ method: 'DELETE', url: `/v1/premiumsubscriptionpayment/${sys_premiumsubscriptionPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Premiumsubscriptionpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getPremiumsubscriptionPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpaymentbyorderid/:orderId` **Rest Request Parameters** The `getPremiumsubscriptionPaymentByOrderId` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.params?.["orderId"] | **orderId** : an ID value to represent the orderId which is the ID parameter of the source premiumsubscription object. The parameter is used to query data. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premiumsubscriptionpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/premiumsubscriptionpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Premiumsubscriptionpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getPremiumsubscriptionPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/premiumsubscriptionpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getPremiumsubscriptionPaymentByPaymentId` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | paymentId | String | true | request.params?.["paymentId"] | **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type. The parameter is used to query data. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/premiumsubscriptionpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/premiumsubscriptionpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_premiumsubscriptionPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_premiumsubscriptionPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Premiumsubscriptionpayment` API Start payment for premiumsubscription **Rest Route** The `startPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/startpremiumsubscriptionpayment/:premiumsubscriptionId` **Rest Request Parameters** The `startPremiumsubscriptionPayment` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | | paymentUserParams | Object | true | request.body?.["paymentUserParams"] | **premiumsubscriptionId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process. Must include paymentMethodId. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startpremiumsubscriptionpayment/:premiumsubscriptionId** ```js axios({ method: 'PATCH', url: `/v1/startpremiumsubscriptionpayment/${premiumsubscriptionId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Premiumsubscriptionpayment` API Refresh payment info for premiumsubscription from Stripe **Rest Route** The `refreshPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/refreshpremiumsubscriptionpayment/:premiumsubscriptionId` **Rest Request Parameters** The `refreshPremiumsubscriptionPayment` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | | paymentUserParams | Object | false | request.body?.["paymentUserParams"] | **premiumsubscriptionId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshpremiumsubscriptionpayment/:premiumsubscriptionId** ```js axios({ method: 'PATCH', url: `/v1/refreshpremiumsubscriptionpayment/${premiumsubscriptionId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Premiumsubscriptionpayment` API Refresh payment values by gateway webhook call for premiumsubscription **Rest Route** The `callbackPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/callbackpremiumsubscriptionpayment` **Rest Request Parameters** The `callbackPremiumsubscriptionPayment` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | false | request.body?.["premiumsubscriptionId"] | **premiumsubscriptionId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackpremiumsubscriptionpayment** ```js axios({ method: 'POST', url: '/v1/callbackpremiumsubscriptionpayment', data: { premiumsubscriptionId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | **userId** : An ID value to represent the user who is created as a stripe customer. The parameter is used to query data. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** **Filter Parameters** The `listPaymentCustomers` api supports 3 optional filter parameters for filtering list results: **userId** (`ID`): An ID value to represent the user who is created as a stripe customer - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **customerId** (`String`): A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway - Single (partial match, case-insensitive): `?customerId=` - Multiple: `?customerId=&customerId=` - Null: `?customerId=null` **platform** (`String`): A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future. - Single (partial match, case-insensitive): `?platform=` - Multiple: `?platform=&platform=` - Null: `?platform=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { // Filter parameters (see Filter Parameters section above) // userId: '' // Filter by userId // customerId: '' // Filter by customerId // platform: '' // Filter by platform } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.["userId"] | **userId** : An ID value to represent the user who owns the payment method. The parameter is used to query data. **Filter Parameters** The `listPaymentCustomerMethods` api supports 6 optional filter parameters for filtering list results: **paymentMethodId** (`String`): A string value to represent the id of the payment method on the payment platform. - Single (partial match, case-insensitive): `?paymentMethodId=` - Multiple: `?paymentMethodId=&paymentMethodId=` - Null: `?paymentMethodId=null` **customerId** (`String`): A string value to represent the customer id which is generated on the payment gateway. - Single (partial match, case-insensitive): `?customerId=` - Multiple: `?customerId=&customerId=` - Null: `?customerId=null` **cardHolderName** (`String`): A string value to represent the name of the card holder. It can be different than the registered customer. - Single (partial match, case-insensitive): `?cardHolderName=` - Multiple: `?cardHolderName=&cardHolderName=` - Null: `?cardHolderName=null` **cardHolderZip** (`String`): A string value to represent the zip code of the card holder. It is used for address verification in specific countries. - Single (partial match, case-insensitive): `?cardHolderZip=` - Multiple: `?cardHolderZip=&cardHolderZip=` - Null: `?cardHolderZip=null` **platform** (`String`): A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future. - Single (partial match, case-insensitive): `?platform=` - Multiple: `?platform=&platform=` - Null: `?platform=null` **cardInfo** (`Object`): A Json value to store the card details of the payment method. - Single: `?cardInfo=` - Multiple: `?cardInfo=&cardInfo=` - Null: `?cardInfo=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { // Filter parameters (see Filter Parameters section above) // paymentMethodId: '' // Filter by paymentMethodId // customerId: '' // Filter by customerId // cardHolderName: '' // Filter by cardHolderName // cardHolderZip: '' // Filter by cardHolderZip // platform: '' // Filter by platform // cardInfo: '' // Filter by cardInfo } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 13 - Profile Service Premiumsubscription Payment Flow** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. ## Stripe Payment Flow For Premiumsubscription `Premiumsubscription` is a data object that stores order information used for Stripe payments. The payment flow can only start after an instance of this data object is created in the database. The ID of this data object—referenced as `premiumsubscriptionId` in the general business logic—will be used as the `orderId` in the payment flow. ## Accessing the service API for the payment flow API The Linkedin application doesn’t have a separate payment service; the payment flow is handled within the same service that manages orders. To access the related APIs, use the base URL of the `profile` service. Note that the application may be deployed to Preview, Staging, or Production. As with all API access, you should call the API using the base URL for the selected deployment. For the `profile` service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/profile-api` * **Staging:** `https://linkedin-stage.mindbricks.co/profile-api` * **Production:** `https://linkedin.mindbricks.co/profile-api` ## Creating the Premiumsubscription While creating the `premiumsubscription` instance is part of the business logic and can be implemented according to your architecture, this instance acts as the central hub for the payment flow and its related data objects. The order object is typically created via its own API (see the Business API for the create route of `premiumsubscription`). The payment flow begins **after** the object is created. Because of the data object’s **Stripe order settings**, the payment flow is aware of the following fields, references, and their purposes: - `id` (used as `orderId` or `${dataObject.objectName}Id`): The unique identifier of the data object instance at the center of the payment flow. - `orderIdProperty`: The order identifier is read from the `id` property of the data object. - `amountProperty`: The payment amount is read from the `price` property of the data object. - `currencyProperty`: The payment currency is read from the `currency` property of the data object. - `description`: The payment description is resolved from `runMScript(() => (`Making subscription for this userId: ${this.premiumsubscription.userId} with profileId: ${this.premiumsubscription.profileId}`), {"path":"services[6].dataObjects[1].objectSettings.stripeOrder.configuration.description"})`. - `orderStatusProperty`: `status` is updated automatically by the payment flow using a mapped status value. - `orderStatusUpdateDateProperty`: `updatedAt` stores the timestamp of the latest payment status update. - `orderOwnerIdProperty`: `userId` is used by the payment flow to verify the order owner and match it with the current user’s ID. - `mapPaymentResultToOrderStatus`: The order status is written to the data object instance using the following mapping. **paymentResultStarted**: `runMScript(() => ("pending"), {"path":"services[6].dataObjects[1].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultStarted"})` **paymentResultCanceled**: `runMScript(() => ("cancelled"), {"path":"services[6].dataObjects[1].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultCanceled"})` **paymentResultFailed**: `runMScript(() => ("declined"), {"path":"services[6].dataObjects[1].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultFailed"})` **paymentResultSuccess**: `runMScript(() => ("completed"), {"path":"services[6].dataObjects[1].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultSuccess"})` ## Before Payment Flow Starts It is assumed that the frontend provides a **“Pay”** or **“Checkout”** button that initiates the payment flow. The following steps occur after the user clicks this button. Note that an `premiumsubscription` instance must already exist to represent the order being paid, with its initial status set. A Stripe payment flow can be implemented in several ways, but the best practice is to use a **PaymentIntent** and manage it jointly from the backend and frontend. A *PaymentIntent* represents the intent to collect payment for a given order (or any payable entity). In the Linkedin application, the **PaymentIntent** is created in the backend, while the **PaymentMethod** (the user’s stored card information) is created in the frontend. Only the PaymentMethod ID and minimal metadata are stored in the backend for later reference. The frontend first requests the current user’s saved payment methods from the backend, displays them in a list, and provides UI options to **add or remove** payment methods. The user must select a Payment Method before starting the payment flow. ### Listing the Payment Methods for the User To list the payment methods of the currently logged-in user, call the following **system API** (unversioned): `GET /payment-methods/list` This endpoint requires no parameters and returns an array of payment methods belonging to the user — without any envelope. ```js const response = await fetch("$serviceUrl/payment-methods/list", { method: "GET", headers: { "Content-Type": "application/json" }, }); ```` Example response: ```json [ { "id": "19a5fbfd-3c25-405b-a7f7-06f023f2ca01", "paymentMethodId": "pm_1SQv9CP5uUv56Cse5BQ3nGW8", "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2", "customerId": "cus_TNgWUw5QkmUPLa", "cardHolderName": "John Doe", "cardHolderZip": "34662", "platform": "stripe", "cardInfo": { "brand": "visa", "last4": "4242", "checks": { "cvc_check": "pass", "address_postal_code_check": "pass" }, "funding": "credit", "exp_month": 11, "exp_year": 2033 }, "isActive": true, "createdAt": "2025-11-07T19:16:38.469Z", "updatedAt": "2025-11-07T19:16:38.469Z", "_owner": "f7103b85-fcda-4dec-92c6-c336f71fd3a2" } ] ``` In each payment method object, the following fields are useful for displaying to the user: ```js for (const method of paymentMethods) { const brand = method.cardInfo.brand; // use brand for displaying VISA/MASTERCARD icons const paymentMethodId = method.paymentMethodId; // send this when initiating the payment flow const cardHolderName = method.cardHolderName; // show in list const number = `**** **** **** ${method.cardInfo.last4}`; // masked card number const expDate = `${method.cardInfo.exp_month}/${method.cardInfo.exp_year}`; // expiry date const id = method.id; // internal DB record ID, used for deletion const customerId = method.customerId; // Stripe customer reference } ``` If the list is empty, prompt the user to **add a new payment method**. ### Creating a Payment Method The payment page (or user profile page) should allow users to add a new payment method (credit card). Creating a Payment Method is a secure operation handled **entirely through Stripe.js** on the frontend — the backend never handles sensitive card data. After a card is successfully created, the backend only stores its reference (PaymentMethod ID) for reuse. Stripe provides multiple ways to collect card information, all through secure UI elements. Below is an example setup — refer to the latest Stripe documentation for alternative patterns. To initialize Stripe on the frontend, include your **public key**: ```html ``` ```js const stripe = Stripe("pk_test_51POkqt4.................."); const elements = stripe.elements(); const cardNumberElement = elements.create("cardNumber", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardNumberElement.mount("#card-number-element"); const cardExpiryElement = elements.create("cardExpiry", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardExpiryElement.mount("#card-expiry-element"); const cardCvcElement = elements.create("cardCvc", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardCvcElement.mount("#card-cvc-element"); // Note: cardholder name and ZIP code are collected via non-Stripe inputs (not secure). ``` You can dynamically show the card brand while typing: ```js cardNumberElement.on("change", (event) => { const cardBrand = event.brand; const cardNumberDiv = document.getElementById("card-number-element"); cardNumberDiv.style.backgroundImage = getBrandImageUrl(cardBrand); }); ``` Once the user completes the card form, create the Payment Method on Stripe. Note that the expiry and CVC fields are securely handled by Stripe.js and are never readable from your code. ```js const { paymentMethod, error } = await stripe.createPaymentMethod({ type: "card", card: cardNumberElement, billing_details: { name: cardholderName.value, address: { postal_code: cardholderZip.value }, }, }); ``` When a `paymentMethod` is successfully created, send its ID to your backend to attach it to the logged-in user’s account. Use the **system API** (unversioned): `POST /payment-methods/add` **Example:** ```js const response = await fetch("$serviceUrl/payment-methods/add", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ paymentMethodId: paymentMethod.id }), }); ``` When `addPaymentMethod` is called, the backend retrieves or creates the user’s Stripe Customer ID, attaches the Payment Method to that customer, and stores the reference in the local database for future use. Example response: ```json { "isActive": true, "cardHolderName": "John Doe", "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2", "customerId": "cus_TNgWUw5QkmUPLa", "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP", "platform": "stripe", "cardHolderZip": "34662", "cardInfo": { "brand": "visa", "last4": "4242", "funding": "credit", "exp_month": 11, "exp_year": 2033 }, "id": "19a5ff70-4986-4760-8fc4-6b591bd6bbbf", "createdAt": "2025-11-07T20:16:55.451Z", "updatedAt": "2025-11-07T20:16:55.451Z" } ``` You can append this new entry directly to the UI list or refresh the list using the `listPaymentMethods` API. ### Deleting a Payment Method To remove a saved payment method from the current user’s account, call the **system API** (unversioned): `DELETE /payment-methods/delete/:paymentMethodId` **Example:** ```js await fetch( `$serviceUrl/payment-methods/delete/${paymentMethodId}`, { method: "DELETE", headers: { "Content-Type": "application/json" }, } ); ``` ## Starting the Payment Flow in Backend — Creation and Confirmation of the PaymentIntent Object The payment flow is initiated in the backend through the `startPremiumsubscriptionPayment` API. This API must be called with one of the user’s existing payment methods. Therefore, ensure that the frontend **forces the user to select a payment method** before initiating the payment. The `startPremiumsubscriptionPayment` API is a versioned **Business Logic API** and follows the same structure as other business APIs. In the Linkedin application, the payment flow starts by creating a **Stripe PaymentIntent** and confirming it in a single step within the backend. In a typical (“happy”) path, when the `startPremiumsubscriptionPayment` API is called, the response will include a successful or failed PaymentIntent result inside the `paymentResult` object, along with the `premiumsubscription` object. However, in certain edge cases—such as when 3D Secure (3DS) or other bank-level authentication is required—the confirmation step cannot complete immediately. In such cases, control should return to a frontend page to allow the user to finish the process. To enable this, a **`return_url`** must be provided during the PaymentIntent creation step. Although technically optional, it is **strongly recommended** to include a `return_url`. This ensures that the frontend payment result page can display both successful and failed payments and complete flows that require user interaction. The `return_url` must be a **frontend URL**. The `paymentUserParams` parameter of the `startPremiumsubscriptionPayment` API contains the data necessary to create the Stripe PaymentIntent. Call the API as follows: ```js const response = await fetch( `$serviceUrl/v1/startpremiumsubscriptionpayment/${orderId}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ paymentUserParams: { paymentMethodId, return_url: `${yourFrontendReturnUrl}`, }, }), } ); ```` The API response will contain a `paymentResult` object. If an error occurs, it will begin with `{ "result": "ERR" }`. Otherwise, it will include the PaymentIntent information: ```json { "paymentResult": { "success": true, "paymentTicketId": "19a60f8f-eeff-43a2-9954-58b18839e1da", "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838", "paymentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8", "paymentStatus": "succeeded", "paymentIntentInfo": { "paymentIntentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8", "clientSecret": "pi_3SR0UHP5uUv56Cse1kwQWCK8_secret_PTc3DriD0YU5Th4isBepvDWdg", "publicKey": "pk_test_51POkqWP5uU", "status": "succeeded" }, "statusLiteral": "success", "amount": 10, "currency": "USD", "description": "Your credit card is charged for babilOrder for 10", "metadata": { "order": "Purchase-Purchase-order", "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838", "checkoutName": "babilOrder" }, "paymentUserParams": { "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP", "return_url": "${yourFrontendReturnUrl}" } } } ``` ### `Start Premiumsubscriptionpayment` API Start payment for premiumsubscription **Rest Route** The `startPremiumsubscriptionPayment` API REST controller can be triggered via the following route: `/v1/startpremiumsubscriptionpayment/:premiumsubscriptionId` **Rest Request Parameters** The `startPremiumsubscriptionPayment` api has got 2 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | premiumsubscriptionId | ID | true | request.params?.["premiumsubscriptionId"] | | paymentUserParams | Object | true | request.body?.["paymentUserParams"] | **premiumsubscriptionId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process. Must include paymentMethodId. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startpremiumsubscriptionpayment/:premiumsubscriptionId** ```js axios({ method: 'PATCH', url: `/v1/startpremiumsubscriptionpayment/${premiumsubscriptionId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "premiumsubscription", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "premiumsubscription": { "id": "ID", "profileId": "ID", "currency": "String", "status": "String", "price": "Double", "userId": "ID", "paymentConfirmation": "Enum", "paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ## Analyzing the API Response After calling the `startPremiumsubscriptionPayment` API, the most common expected outcome is a confirmed and completed payment. However, several alternate cases should be handled on the frontend. ### System Error Case The API may return a classic service-level error (unrelated to payment). Check the HTTP status code of the response. It should be `200` or `201`. Any `400`, `401`, `403`, or `404` indicates a system error. ```json { "result": "ERR", "status": 404, "message": "Record not found", "date": "2025-11-08T00:57:54.820Z" } ``` **Handle system errors on the payment page** (show a retry option). Do not navigate to the result page. ### Payment Error Case The API performs both database operations and the Stripe payment operation. If the payment fails but the service logic succeeds, the API may still return a `200 OK` status, with the failure recorded in the `paymentResult`. In this case, show an error message and allow the user to retry. ```json { "status": "OK", "statusCode": "200", "premiumsubscription": { "id": "19a60f8f-eeff-43a2-9954-58b18839e1da", "status": "failed" }, "paymentResult": { "result": "ERR", "status": 500, "message": "Stripe error message: Your card number is incorrect.", "errCode": "invalid_number", "date": "2025-11-08T00:57:54.820Z" } } ``` **Payment errors should be handled on the payment page** (retry option). Do not go to the result page. --- ### Happy Case When both the service and payment result succeed, this is considered the *happy path*. In this case, use the `premiumsubscription` and `paymentResult` objects in the response to display a success message to the user. `amount` and `description` values are included to help you show payment details on the result page. ```json { "status": "OK", "statusCode": "200", "order": { "id": "19a60f8f-eeff-43a2-9954-58b18839e1da", "status": "paid" }, "paymentResult": { "success": true, "paymentStatus": "succeeded", "paymentIntentInfo": { "status": "succeeded" }, "amount": 10, "currency": "USD", "description": "Your credit card is charged for babilOrder for 10" } } ``` To verify success: ```js if (paymentResult.paymentIntentInfo.status === "succeeded") { // Redirect to result page } ``` > Note: A successful result does not trigger fulfillment immediately. > Fulfillment begins only after the Stripe webhook updates the database. > It’s recommended to show a short “success” toast, wait a few milliseconds, and then navigate to the result page. **Handle the happy case in the result page** by sending the `premiumsubscriptionId` and the payment intent secret. ```js const orderId = new URLSearchParams(window.location.search).get("orderId"); const url = new URL(`$yourResultPageUrl`, location.origin); url.searchParams.set("orderId", orderId); url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret); setTimeout(() => { window.location.href = url.toString(); }, 600); ``` --- ### Edge Cases Although `startPremiumsubscriptionPayment` is designed to handle both creation and confirmation in one step, Stripe may return an incomplete result if third-party authentication or redirect steps are required. You must handle these cases in **both the payment page and the result page**, because some next actions are available immediately, while others occur only after a redirect. If the `paymentIntentInfo.status` equals `"requires_action"`, handle it using Stripe.js as shown below: ```js if (paymentResult.paymentIntentInfo.status === "requires_action") { await runNextAction( paymentResult.paymentIntentInfo.clientSecret, paymentResult.paymentIntentInfo.publicKey ); } ``` Helper function: ```js async function runNextAction(clientSecret, publicKey) { const stripe = Stripe(publicKey); const { error } = await stripe.handleNextAction({ clientSecret }); if (error) { console.log("next_action error:", error); showToast(error.code + ": " + error.message, "fa-circle-xmark text-red-500"); throw new Error(error.message); } } ``` After handling the next action, re-fetch the PaymentIntent from Stripe, evaluate its status, show appropriate feedback, and navigate to the result page. ```js const { paymentIntent } = await stripe.retrievePaymentIntent(clientSecret); if (paymentIntent.status === "succeeded") { showToast("Payment successful!", "fa-circle-check text-green-500"); } else if (paymentIntent.status === "processing") { showToast("Payment is processing…", "fa-circle-info text-blue-500"); } else if (paymentIntent.status === "requires_payment_method") { showToast("Payment failed. Try another card.", "fa-circle-xmark text-red-500"); } const orderId = new URLSearchParams(window.location.search).get("orderId"); const url = new URL(`$yourResultPageUrl`, location.origin); url.searchParams.set("orderId", orderId); url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret); setTimeout(() => { window.location.href = url.toString(); }, 600); ``` --- ## The Result Page The payment result page should handle the following steps: 1. Read `orderId` and `payment_intent_client_secret` from the query parameters. 2. Retrieve the PaymentIntent from Stripe and check its status. 3. If required, handle any `next_action` and re-fetch the PaymentIntent. 4. If the status is `"succeeded"`, display a clear visual confirmation. 5. Fetch the `premiumsubscription` instance from the backend to display any additional order or fulfillment details. Note that paymentIntent status only gives information about the Stripe side. The `premiumsubscription` instance in the service should also ve updated to start the fulfillment. In most cases, the `startpremiumsubscriptionPayment` api updates the status of the order using the response of the paymentIntent confirmation, but as stated above in some cases this update can be done only when the webhook executes. So in teh result page always get the final payment status in the `premiumsubscription. To ensure that service i To fetch the `premiumsubscription` instance, you van use the related api which is given before, and to ensure that the service is updated with the latest status read the paymentConfirmation field of the `premiumsubscription` instance. ```js if (premiumsubscription.paymentConfirmation == "canceled") { // the payment is canceled, user can be informed that they should try again } if (premiumsubscription.paymentConfirmation == "paid") { // service knows that payment is done, user can be informed that fullfillment started } else { // it may be pending, processing // Fetch the object again until a canceled or paid status } ``` --- ## Payment Flow via MCP (AI Chat Integration) The payment flow is also accessible through the MCP (Model Context Protocol) AI chat interface. The `profile` service exposes an `initiatePayment` MCP tool that the AI can call when the user wants to pay for an order. ### How initiatePayment Works in MCP 1. **User asks to pay** — e.g., "I want to pay for my order" 2. **AI calls `initiatePayment`** MCP tool with `orderId` (and `orderType` if multiple order types exist) 3. **Tool validates** the order exists, is payable, and the user is authorized 4. **Tool returns `__frontendAction`** with `type: "payment"` — this is NOT a direct payment execution 5. **Frontend chat UI** renders a `PaymentActionCard` with a "Pay Now" button 6. **User clicks "Pay Now"** — the frontend opens a payment modal with `CheckoutForm` 7. **Standard Stripe flow** proceeds (payment method selection, 3DS handling, etc.) ### Frontend Action Response Format The `initiatePayment` MCP tool returns: ```json { "__frontendAction": { "type": "payment", "orderId": "uuid", "orderType": "premiumsubscription", "serviceName": "profile", "amount": 99.99, "currency": "USD", "description": "Order description" }, "message": "Payment is ready. Click the button below to proceed." } ``` ### MCP Client Architecture The frontend communicates with MCP tools through the **MCP BFF** (Backend-for-Frontend) service. The MCP BFF aggregates tool calls across all backend services and provides: - **SSE Streaming**: Chat messages stream via `/api/chat/stream` with event types: `start`, `text`, `tool_start`, `tool_executing`, `tool_result`, `error`, `done` - **Tool Result Extraction**: The frontend's `MessageBubble` component inspects tool results for `__frontendAction` fields - **Action Dispatch**: The `ActionCard` component dispatches to type-specific cards (e.g., `PaymentActionCard` for `type: "payment"`) The `PaymentActionCard` component handles the rest: fetching order details, rendering the payment UI, and completing the Stripe checkout flow — all within the chat interface. --- # **LINKEDIN** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 14 - AgentHub Service** This document is a part of a REST API guide for the linkedin project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of agentHub ## Service Access AgentHub service management is handled through service specific base urls. AgentHub service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the agentHub service, the base URLs are: * **Preview:** `https://linkedin.prw.mindbricks.com/agenthub-api` * **Staging:** `https://linkedin-stage.mindbricks.co/agenthub-api` * **Production:** `https://linkedin.mindbricks.co/agenthub-api` ## Scope **AgentHub Service Description** AI Agent Hub AgentHub service provides apis and business logic for following data objects in linkedin application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`sys_agentOverride` Data Object**: Runtime overrides for design-time agents. Null fields use the design default. **`sys_agentExecution` Data Object**: Agent execution log. Records each agent invocation with input, output, and performance metrics. **`sys_toolCatalog` Data Object**: Cached tool catalog discovered from project services. Refreshed periodically. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Sys_agentOverride Data Object Runtime overrides for design-time agents. Null fields use the design default. ### Sys_agentOverride Data Object Properties Sys_agentOverride data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `agentName` | String | | Yes | No | Design-time agent name this override applies to. | | `provider` | String | | No | No | Override AI provider (e.g., openai, anthropic). | | `model` | String | | No | No | Override model name. | | `systemPrompt` | Text | | No | No | Override system prompt. | | `temperature` | Double | | No | No | Override temperature (0-2). | | `maxTokens` | Integer | | No | No | Override max tokens. | | `responseFormat` | String | | No | No | Override response format (text/json). | | `selectedTools` | Object | | No | No | Array of tool names from the catalog that this agent can use. | | `guardrails` | Object | | No | No | Override guardrails: { maxToolCalls, timeout, maxTokenBudget }. | | `enabled` | Boolean | | Yes | No | Enable or disable this agent. | | `updatedBy` | ID | | No | No | User who last updated this override. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ## Sys_agentExecution Data Object Agent execution log. Records each agent invocation with input, output, and performance metrics. ### Sys_agentExecution Data Object Properties Sys_agentExecution data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `agentName` | String | | Yes | No | Agent that was executed. | | `agentType` | Enum | | Yes | No | Whether this was a design-time or dynamic agent. | | `source` | Enum | | Yes | No | How the agent was triggered. | | `userId` | ID | | No | No | User who triggered the execution. | | `input` | Object | | No | No | Request input (truncated for large payloads). | | `output` | Object | | No | No | Response output (truncated for large payloads). | | `toolCalls` | Integer | | No | No | Number of tool calls made during execution. | | `tokenUsage` | Object | | No | No | Token usage: { prompt, completion, total }. | | `durationMs` | Integer | | No | No | Execution time in milliseconds. | | `status` | Enum | | Yes | No | Execution status. | | `error` | Text | | No | No | Error message if execution failed. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **agentType**: [design, dynamic] - **source**: [rest, sse, kafka, agent] - **status**: [success, error, timeout] ### Filter Properties `agentName` `agentType` `source` `userId` `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **agentName**: String has a filter named `agentName` - **agentType**: Enum has a filter named `agentType` - **source**: Enum has a filter named `source` - **userId**: ID has a filter named `userId` - **status**: Enum has a filter named `status` ## Sys_toolCatalog Data Object Cached tool catalog discovered from project services. Refreshed periodically. ### Sys_toolCatalog Data Object Properties Sys_toolCatalog data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `toolName` | String | | Yes | No | Full tool name (e.g., service:apiName). | | `serviceName` | String | | Yes | No | Source service name. | | `description` | Text | | No | No | Tool description. | | `parameters` | Object | | No | No | JSON Schema of tool parameters. | | `lastRefreshed` | Date | | No | No | When this tool was last discovered/refreshed. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `serviceName` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **serviceName**: String has a filter named `serviceName` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### Sys_agentOverride Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createAgentOverride` | `/v1/agentoverride` | Yes | | Update | `updateAgentOverride` | `/v1/agentoverride/:sys_agentOverrideId` | Yes | | Delete | `deleteAgentOverride` | `/v1/agentoverride/:sys_agentOverrideId` | Yes | | Get | `getAgentOverride` | `/v1/agentoverride/:sys_agentOverrideId` | Yes | | List | `listAgentOverrides` | `/v1/agentoverrides` | Yes | ### Sys_agentExecution Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | `getAgentExecution` | `/v1/agentexecution/:sys_agentExecutionId` | Yes | | List | `listAgentExecutions` | `/v1/agentexecutions` | Yes | ### Sys_toolCatalog Default APIs | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | _none_ | - | Auto | | Update | _none_ | - | Auto | | Delete | _none_ | - | Auto | | Get | `getToolCatalogEntry` | `/v1/toolcatalogentry/:sys_toolCatalogId` | Yes | | List | `listToolCatalog` | `/v1/toolcatalog` | Yes | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## API Reference ### `Get Agentoverride` API **[Default get API]** — This is the designated default `get` API for the `sys_agentOverride` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `getAgentOverride` API REST controller can be triggered via the following route: `/v1/agentoverride/:sys_agentOverrideId` **Rest Request Parameters** The `getAgentOverride` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_agentOverrideId | ID | true | request.params?.["sys_agentOverrideId"] | **sys_agentOverrideId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/agentoverride/:sys_agentOverrideId** ```js axios({ method: 'GET', url: `/v1/agentoverride/${sys_agentOverrideId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentOverride", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_agentOverride": { "id": "ID", "agentName": "String", "provider": "String", "model": "String", "systemPrompt": "Text", "temperature": "Double", "maxTokens": "Integer", "responseFormat": "String", "selectedTools": "Object", "guardrails": "Object", "enabled": "Boolean", "updatedBy": "ID", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true } } ``` ### `List Agentoverrides` API **[Default list API]** — This is the designated default `list` API for the `sys_agentOverride` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `listAgentOverrides` API REST controller can be triggered via the following route: `/v1/agentoverrides` **Rest Request Parameters** The `listAgentOverrides` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/agentoverrides** ```js axios({ method: 'GET', url: '/v1/agentoverrides', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentOverrides", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_agentOverrides": [ { "id": "ID", "agentName": "String", "provider": "String", "model": "String", "systemPrompt": "Text", "temperature": "Double", "maxTokens": "Integer", "responseFormat": "String", "selectedTools": "Object", "guardrails": "Object", "enabled": "Boolean", "updatedBy": "ID", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Agentoverride` API **[Default update API]** — This is the designated default `update` API for the `sys_agentOverride` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `updateAgentOverride` API REST controller can be triggered via the following route: `/v1/agentoverride/:sys_agentOverrideId` **Rest Request Parameters** The `updateAgentOverride` api has got 10 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_agentOverrideId | ID | true | request.params?.["sys_agentOverrideId"] | | provider | String | | request.body?.["provider"] | | model | String | | request.body?.["model"] | | systemPrompt | Text | | request.body?.["systemPrompt"] | | temperature | Double | | request.body?.["temperature"] | | maxTokens | Integer | | request.body?.["maxTokens"] | | responseFormat | String | | request.body?.["responseFormat"] | | selectedTools | Object | | request.body?.["selectedTools"] | | guardrails | Object | | request.body?.["guardrails"] | | enabled | Boolean | | request.body?.["enabled"] | **sys_agentOverrideId** : This id paremeter is used to select the required data object that will be updated **provider** : Override AI provider (e.g., openai, anthropic). **model** : Override model name. **systemPrompt** : Override system prompt. **temperature** : Override temperature (0-2). **maxTokens** : Override max tokens. **responseFormat** : Override response format (text/json). **selectedTools** : Array of tool names from the catalog that this agent can use. **guardrails** : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }. **enabled** : Enable or disable this agent. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/agentoverride/:sys_agentOverrideId** ```js axios({ method: 'PATCH', url: `/v1/agentoverride/${sys_agentOverrideId}`, data: { provider:"String", model:"String", systemPrompt:"Text", temperature:"Double", maxTokens:"Integer", responseFormat:"String", selectedTools:"Object", guardrails:"Object", enabled:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentOverride", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_agentOverride": { "id": "ID", "agentName": "String", "provider": "String", "model": "String", "systemPrompt": "Text", "temperature": "Double", "maxTokens": "Integer", "responseFormat": "String", "selectedTools": "Object", "guardrails": "Object", "enabled": "Boolean", "updatedBy": "ID", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true } } ``` ### `Create Agentoverride` API **[Default create API]** — This is the designated default `create` API for the `sys_agentOverride` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `createAgentOverride` API REST controller can be triggered via the following route: `/v1/agentoverride` **Rest Request Parameters** The `createAgentOverride` api has got 9 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | agentName | String | true | request.body?.["agentName"] | | provider | String | false | request.body?.["provider"] | | model | String | false | request.body?.["model"] | | systemPrompt | Text | false | request.body?.["systemPrompt"] | | temperature | Double | false | request.body?.["temperature"] | | maxTokens | Integer | false | request.body?.["maxTokens"] | | responseFormat | String | false | request.body?.["responseFormat"] | | selectedTools | Object | false | request.body?.["selectedTools"] | | guardrails | Object | false | request.body?.["guardrails"] | **agentName** : Design-time agent name this override applies to. **provider** : Override AI provider (e.g., openai, anthropic). **model** : Override model name. **systemPrompt** : Override system prompt. **temperature** : Override temperature (0-2). **maxTokens** : Override max tokens. **responseFormat** : Override response format (text/json). **selectedTools** : Array of tool names from the catalog that this agent can use. **guardrails** : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/agentoverride** ```js axios({ method: 'POST', url: '/v1/agentoverride', data: { agentName:"String", provider:"String", model:"String", systemPrompt:"Text", temperature:"Double", maxTokens:"Integer", responseFormat:"String", selectedTools:"Object", guardrails:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentOverride", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_agentOverride": { "id": "ID", "agentName": "String", "provider": "String", "model": "String", "systemPrompt": "Text", "temperature": "Double", "maxTokens": "Integer", "responseFormat": "String", "selectedTools": "Object", "guardrails": "Object", "enabled": "Boolean", "updatedBy": "ID", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true } } ``` ### `Delete Agentoverride` API **[Default delete API]** — This is the designated default `delete` API for the `sys_agentOverride` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `deleteAgentOverride` API REST controller can be triggered via the following route: `/v1/agentoverride/:sys_agentOverrideId` **Rest Request Parameters** The `deleteAgentOverride` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_agentOverrideId | ID | true | request.params?.["sys_agentOverrideId"] | **sys_agentOverrideId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/agentoverride/:sys_agentOverrideId** ```js axios({ method: 'DELETE', url: `/v1/agentoverride/${sys_agentOverrideId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentOverride", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_agentOverride": { "id": "ID", "agentName": "String", "provider": "String", "model": "String", "systemPrompt": "Text", "temperature": "Double", "maxTokens": "Integer", "responseFormat": "String", "selectedTools": "Object", "guardrails": "Object", "enabled": "Boolean", "updatedBy": "ID", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": false } } ``` ### `List Toolcatalog` API **[Default list API]** — This is the designated default `list` API for the `sys_toolCatalog` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `listToolCatalog` API REST controller can be triggered via the following route: `/v1/toolcatalog` **Rest Request Parameters** **Filter Parameters** The `listToolCatalog` api supports 1 optional filter parameter for filtering list results: **serviceName** (`String`): Source service name. - Single (partial match, case-insensitive): `?serviceName=` - Multiple: `?serviceName=&serviceName=` - Null: `?serviceName=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/toolcatalog** ```js axios({ method: 'GET', url: '/v1/toolcatalog', data: { }, params: { // Filter parameters (see Filter Parameters section above) // serviceName: '' // Filter by serviceName } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_toolCatalogs", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_toolCatalogs": [ { "id": "ID", "toolName": "String", "serviceName": "String", "description": "Text", "parameters": "Object", "lastRefreshed": "Date", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Toolcatalogentry` API **[Default get API]** — This is the designated default `get` API for the `sys_toolCatalog` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `getToolCatalogEntry` API REST controller can be triggered via the following route: `/v1/toolcatalogentry/:sys_toolCatalogId` **Rest Request Parameters** The `getToolCatalogEntry` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_toolCatalogId | ID | true | request.params?.["sys_toolCatalogId"] | **sys_toolCatalogId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/toolcatalogentry/:sys_toolCatalogId** ```js axios({ method: 'GET', url: `/v1/toolcatalogentry/${sys_toolCatalogId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_toolCatalog", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_toolCatalog": { "id": "ID", "toolName": "String", "serviceName": "String", "description": "Text", "parameters": "Object", "lastRefreshed": "Date", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true } } ``` ### `List Agentexecutions` API **[Default list API]** — This is the designated default `list` API for the `sys_agentExecution` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `listAgentExecutions` API REST controller can be triggered via the following route: `/v1/agentexecutions` **Rest Request Parameters** **Filter Parameters** The `listAgentExecutions` api supports 5 optional filter parameters for filtering list results: **agentName** (`String`): Agent that was executed. - Single (partial match, case-insensitive): `?agentName=` - Multiple: `?agentName=&agentName=` - Null: `?agentName=null` **agentType** (`Enum`): Whether this was a design-time or dynamic agent. - Single: `?agentType=` (case-insensitive) - Multiple: `?agentType=&agentType=` - Null: `?agentType=null` **source** (`Enum`): How the agent was triggered. - Single: `?source=` (case-insensitive) - Multiple: `?source=&source=` - Null: `?source=null` **userId** (`ID`): User who triggered the execution. - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **status** (`Enum`): Execution status. - Single: `?status=` (case-insensitive) - Multiple: `?status=&status=` - Null: `?status=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/agentexecutions** ```js axios({ method: 'GET', url: '/v1/agentexecutions', data: { }, params: { // Filter parameters (see Filter Parameters section above) // agentName: '' // Filter by agentName // agentType: '' // Filter by agentType // source: '' // Filter by source // userId: '' // Filter by userId // status: '' // Filter by status } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentExecutions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_agentExecutions": [ { "id": "ID", "agentName": "String", "agentType": "Enum", "agentType_idx": "Integer", "source": "Enum", "source_idx": "Integer", "userId": "ID", "input": "Object", "output": "Object", "toolCalls": "Integer", "tokenUsage": "Object", "durationMs": "Integer", "status": "Enum", "status_idx": "Integer", "error": "Text", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Agentexecution` API **[Default get API]** — This is the designated default `get` API for the `sys_agentExecution` data object. Frontend generators and AI agents should use this API for standard CRUD operations. **Rest Route** The `getAgentExecution` API REST controller can be triggered via the following route: `/v1/agentexecution/:sys_agentExecutionId` **Rest Request Parameters** The `getAgentExecution` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_agentExecutionId | ID | true | request.params?.["sys_agentExecutionId"] | **sys_agentExecutionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/agentexecution/:sys_agentExecutionId** ```js axios({ method: 'GET', url: `/v1/agentexecution/${sys_agentExecutionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_agentExecution", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_agentExecution": { "id": "ID", "agentName": "String", "agentType": "Enum", "agentType_idx": "Integer", "source": "Enum", "source_idx": "Integer", "userId": "ID", "input": "Object", "output": "Object", "toolCalls": "Integer", "tokenUsage": "Object", "durationMs": "Integer", "status": "Enum", "status_idx": "Integer", "error": "Text", "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "isActive": true } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** --- --- ## Related Documentation For more detailed information, refer to: - **[llms.txt](/document/llms.txt)** - Documentation overview and index - **[llms-restapi.txt](/document/llms-restapi.txt)** - Complete REST API reference - **[llms-full.txt](/document/llms-full.txt)** - Complete documentation --- *Generated by Mindbricks Genesis Engine*