API Modelling

Overview

K5 SDK enables API modelling for NestJS-based applications, allowing users to define API namespaces through the Solution Designer, resulting in OpenAPI 3 specification files.

When API Modelling is enabled, the K5 SDK provides modules and controllers for implementing the API namespaces. Additionally, enabling swaggerUISupport allows automatic Swagger UI generation, accessible at http://localhost:3000/swagger-ui/index.html during local development, see also Swagger UI.

ℹ️note

API modelling is controlled via the project configuration file k5-project.yml

Generated API Namespace Structure

Once API modelling is enabled, running k5 generate-code command generates the required modules and controllers, automatically wiring them into the application for example:

├── src
│   ├── api
│   │   ├── pet
│   │   │   ├── pet.controller.ts
│   │   │   ├── pet.module.ts
│   │   │   ├── store.controller.ts
│   │   │   └── user.controller.ts
│   │   └── pro
│   │       ├── default.controller.ts
│   │       ├── pro.module.ts
│   │       └── public.controller.ts
│   ├── app.module.ts
│   ├── generated
│   │   ├── .gitignore
│   │   └── api
│   │       ├── index.ts
│   │       ├── pet.controllers.ts
│   │       └── pro.controllers.ts

Implementation files

• The src/api directory is where API namespace modules and controllers are generated, where business logic and customisation can be implemented, e.g. for pet API namespace:
  • src/api/pet/pet.module.ts is the generated pet API namespace module.
  • src/api/pet/pet.controller.ts is one of the generated controllers of the pet API namespace module.

Pet API Controller:

import { UsePipes } from '@nestjs/common';
import { K5LoggerService, K5APIValidationPipe, PetAPI } from 'k5-sdk';

@PetAPI.PetServiceControllerDecorator
@UsePipes(K5APIValidationPipe)
export class PetServiceController extends PetAPI.PetServiceControllerBase {
  constructor(private readonly logger: K5LoggerService) {
    super();
  }

  /**
   * Add a new pet to the store
   * @param { PetAPI.AddPetRequest } req - Express request.
   * @param { PetAPI.AddPetResponse } res - Express response.
   * @return {Promise<AddPetResponseBody>} A promise returning the response body.
   */
  async addPet(req: PetAPI.AddPetRequest, res: PetAPI.AddPetResponse): Promise<PetAPI.AddPetResponseBody> {
    this.logger.info(`Starting "addPet" operation`);
    throw new Error(`Operation "addPet" is not implemented`);
  }
}

Helper generated files

• The src/generated directory contains utility helpers that:
  • Export each API namespace’s controllers to be used within each API namespace module (e.g., src/generated/api/pet.controllers.ts).
  • Export an array of all API namespace modules to be used within app.module.ts (src/generated/api/index.ts).
  • The src/generated directory will be automatically overwritten after each code generation and therefore is git-ignored.

The generated API namespaces modules are automatically imported from @generated/api into app.module.ts:

import { ConfigModule } from '@nestjs/config';
import { Module } from '@nestjs/common';
import { K5SDKModule } from 'k5-sdk';
import { APINamespaceModules } from '@generated/api';

@Module({
  imports: [
    ConfigModule.forRoot(),
    K5SDKModule.forRoot({}),
    /** All modelled API namespace modules */
    ...APINamespaceModules,
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

The controllers of an API namespace are automatically imported into the generated API namespace module, for example the PetAPIModule imports all of the pet API controllers:

import { Module } from '@nestjs/common';
import { PetAPIControllers } from '@generated/api/pet.controllers';

@Module({
  imports: [],
  controllers: [
    /** All the controllers of the pet API namespace */
    ...PetAPIControllers,
  ],
  providers: [],
})
export class PetAPIModule {}

Security & Validation

Authentication

The generated API endpoints are protected by default using JWT based authentication, to disable authentication for certain endpoints or controllers, refer to disable JWT authentication.

Request Validation

By default, all generated controllers use the K5APIValidationPipe to validate incoming requests, ensuring compliance with the API specification. To disable or customize this validation, users can remove the pipe or implement their own validation pipes.

Swagger UI representation

If swaggerUISupport extension is enabled, then the modelled API namespaces can be easily consumed through the browser, more information on Swagger UI