Skip to main content

Overview

1. Introduction​

An Application Programming Interface (API) is a software intermediary that enables applications to communicate with one another. APIs allow enterprises to provide secure access to the functionality and data of their systems for both internal and external developers.

2. Working of API​

APIs work through request–response communication between a client (front end) and a server (back end). The API acts as a middle layer, routing requests from clients to servers, processing data, and returning responses.

3. API Components​

An API consists of two primary components:

  • Technical Specification: Defines the data exchange protocols and methods.
  • Software Interface: The implementation of the technical specification that enables interaction between systems.

4. Types of API​

1. Open APIs​

Open APIs, also called public APIs, are available to all users. They allow external users to access data and services. They are accessible using HTTP protocols.

2. Internal APIs​

Internal APIs, also known as private APIs, are exposed only within an organization. They are designed for internal use rather than external consumption.

3. Composite APIs​

Composite APIs combine multiple data sources or services into a single request. They improve performance and reduce the number of requests required.

4. Partner APIs​

Partner APIs require specific access rights or licenses. They are not publicly available and are shared with selected business partners.

5. Use Cases of API​

APIs are used in various scenarios, including:

  • Database APIs: Enable communication between applications and database systems. Developers use tools like Prisma to manage databases such as PostgreSQL.
  • Operating System APIs: Allow applications to interact with system resources in operating systems like Linux and Windows.
  • Remote APIs: Enable communication between applications running on different machines. For example, a NestJS API provides RESTful endpoints for distributed systems.
  • Web APIs: Facilitate communication between frontend applications (e.g., Next.js) and backend services over HTTP.

6. API Protocols​

An API protocol defines how a client and server communicate, including request/response formats, supported operations, and rules for accessing endpoints.

The current system architecture uses REST over HTTP as the API communication standard, with JSON as the primary data format. The backend exposes resource-based endpoints, and the client interacts with them using standard HTTP methods.

Representational State Transfer (REST)​

The current architecture follows the REST protocol. REST is suitable because it supports a clear separation between client and server, uses standard web conventions, and integrates easily with browser-based applications.

Communication is performed through HTTP requests and responses, and data is exchanged in JSON format.

A REST request typically contains the following components:

HTTP Method​

Defines the action to be performed on the resource, such as GET, POST, PATCH, or DELETE.

Endpoint​

Defines the resource path being accessed, such as /health, /auth/login, /api/v1/auth/me, or /api/v1/systems.

Carries request metadata such as content type, accepted response type, and authentication information.

Body​

Contains data sent from the client to the server, usually in JSON format for create or update operations.

Protocol Used in the Current Architecture​

The current implementation uses:

  • REST over HTTP
  • JSON-based request and response payloads
  • Resource-oriented endpoint design
  • Standard HTTP methods for CRUD operations
  • Standard HTTP status codes for responses

This structure supports a clear client–server separation, where the frontend communicates with the backend via HTTP endpoints and receives structured responses for rendering and processing.

Protocols Not Implemented in the Current Architecture​

The system does not use the following protocols:

  • SOAP
  • gRPC
  • JSON-RPC
  • GraphQL
  • Apache Thrift

Although these protocols exist in other systems, they are not part of the current architecture. This documentation focuses only on REST, which is currently implemented.

Summary​

In the current architecture, the API protocol used is REST. Communication occurs over HTTP, data is exchanged in JSON format, and the backend is organized around resource-based endpoints consumed by the client application.

7. Examples of API​

Examples of APIs based on the current project implementation include:

Health Check API​

Used to verify that the application and database are running properly through the /health endpoint.

Authentication API​

Used to handle the login flow, authentication callback, token refresh, logout, and user profile retrieval.
Endpoints include:

  • /auth/login
  • /auth/callback
  • /auth/refresh
  • /auth/logout
  • /api/v1/auth/me

Employee API​

Used to retrieve employee information based on companyCode and employeeNumber through the following endpoint:

  • /api/v1/employees/:companyCode/:employeeNumber

System Master API​

Used to manage master data through the following endpoints:

  • GET /api/v1/systems
  • POST /api/v1/systems
  • PATCH /api/v1/systems/:id
  • DELETE /api/v1/systems/:id

Frontend Proxy / API Integration​

Used by the frontend application to communicate with backend services through a centralized request flow, including automatic session refresh when access tokens expire. [image]

8.1 UI Structure and Configuration Guideline​

This section describes the frontend structure and configuration used in the current architecture.

The user interface is implemented using Next.js with the App Router pattern. The frontend is organized into route groups such as authenticated pages and authentication pages. Reusable UI components are placed in shared component folders. Styling and UI behavior are based on the existing theme, global styles, and reusable component patterns defined in the codebase.

For UI development, the current structure uses:

  • Next.js for the frontend framework
  • React for component-based UI development
  • Mantine UI as the main component library
  • next-intl for localization support
  • TanStack Query and shared service utilities for client–server data interaction

For UX development, design references and wireframes may be prepared externally. However, the implemented frontend structure is based on the component and layout patterns already available in the codebase.

For more details, refer to the frontend structure under apps/web.

8.2 API Structure and Configuration Guideline​

This section describes the API structure and configuration used in the current backend architecture.

The API is implemented using NestJS with a feature-based module structure. Each module is separated by responsibility, such as authentication, health checks, employee data, and system master data. The backend also applies global validation, authentication guards, rate limiting (throttling), serialization, and environment validation during application startup.

The API is configured to use:

  • REST over HTTP
  • JSON request and response payloads
  • Prisma for database access
  • Zod for request and response validation
  • Swagger / OpenAPI for API documentation
  • Environment-based configuration validation

For more details, refer to the backend structure under apps/api.

8.3 Security Configuration Guideline​

This section describes the security-related configuration applied in the current architecture.

The backend includes several security controls as part of the application bootstrap and authentication flow. These include security headers, cookie-based authentication, JWT validation, request throttling, CORS configuration, and environment variable validation.

The current security implementation includes:

  • Helmet for HTTP security headers
  • JWT authentication guard applied globally
  • HTTP-only cookies for token handling
  • Refresh token rotation for improved session security
  • CORS configuration aligned with the frontend origin
  • Rate limiting using throttling guards
  • Signed login state handling for authentication flow validation

For more details, refer to the authentication and bootstrap configuration under:

  • apps/api/src/auth
  • apps/api/src/app.module.ts
  • apps/api/src/main.ts

8.4 Automated Test Configuration Guidelines​

This section describes the automated testing approach used in the current architecture.

The project includes multiple layers of automated testing to validate different parts of the system:

  • Unit tests for individual functions and business logic
  • Module-level tests for backend and frontend components
  • API collection tests for endpoint validation
  • End-to-end (E2E) tests for full user flow validation in a browser environment

The current automated test setup includes:

  • Jest for unit and component testing
  • Supertest for backend endpoint-level testing
  • Bruno for API collection testing
  • Robot Framework for end-to-end UI automation
  • Selenium Grid for distributed browser-based test execution

For more details, refer to:

  • apps/api/src/**/*.spec.ts
  • apps/web/__tests__
  • tests/api
  • tests/e2e

8.5 Shared Service and Common Configuration Guidelines​

This section describes shared services and common configurations used across the current architecture.

The system uses shared packages and centralized service utilities to reduce duplication between applications. Shared schemas ensure request and response contracts remain consistent, while frontend request handling is centralized through a dedicated fetcher service. Common environment configurations are also shared across local development and containerized environments.

The shared and common configuration currently includes:

  • Shared schemas in packages/schemas
  • Shared constants in packages/constants
  • Centralized frontend request handling in apps/web/src/services
  • Database and infrastructure configuration in infra/db
  • Container-based local setup via docker-compose.yaml

For more details, refer to the packages, infra, and frontend service structure in the repository.

8.6 CI/CD Pipeline Configuration Guidelines​

This section describes the technical approach that supports build, test, and deployment preparation in the current architecture.

The project is structured as a monorepo, so build and validation steps are managed at the workspace level. The repository includes commands for installing dependencies, running lint checks, executing tests, building applications, and starting the local container-based environment. It also includes infrastructure and test assets that ensure consistent execution across development and delivery workflows.

The current pipeline-related structure includes:

  • PNPM workspace for monorepo dependency and script management
  • Build scripts for frontend, backend, and shared packages
  • Linting and formatting using ESLint and Prettier
  • Automated tests across frontend, backend, API, and E2E layers
  • Docker Compose for consistent environment setup
  • Observability stack configuration for local monitoring support

For more details, refer to:

  • package.json
  • pnpm-workspace.yaml
  • docker-compose.yaml
  • docker-compose.observability.yaml
  • Makefile