Syneo/Barcoding

Appearance

Getting Started with API ​

This guide will help you set up and start developing with the Syneo/Barcoding API.

Prerequisites ​

  • Node.js >= 10 (recommended: 18 or 20 LTS)
  • npm or yarn
  • MySQL server
  • Git

Installation ​

1. Navigate to API Directory ​

bash
cd api/b3api

2. Install Dependencies ​

bash
npm install

Configuration ​

Database Setup ​

Ensure MySQL is running and accessible with the development credentials:

json
{
  "host": "mysqldb",
  "port": 3306,
  "user": "root",
  "password": "Ypp01o#3",
  "database": "lb4"
}

Run Migrations ​

bash
npm run migrate

This will create all necessary tables and schema in the database.

Development ​

Build the API ​

bash
# One-time build
npm run build

# Watch mode (rebuilds on changes)
npm run build:watch

Start the API ​

bash
# Start with debugger (recommended)
npm run start

# Or with nodemon and watch mode
npm run run:dev

The API will be available at:

  • Base URL: http://localhost:3001
  • REST Explorer: http://localhost:3001/explorer
  • OpenAPI Spec: http://localhost:3001/openapi.json

Verify Installation ​

1. Check API Health ​

Open a browser and navigate to:

http://localhost:3001/ping

You should see:

json
{
  "greeting": "Hello from LoopBack",
  "date": "2025-12-10T12:00:00.000Z"
}

2. Explore API ​

Visit the REST Explorer:

http://localhost:3001/explorer

You'll see all 606+ API endpoints organized by controller.

3. Test an Endpoint ​

In the Explorer:

  1. Click on any controller (e.g., "TicketController")
  2. Select a GET endpoint
  3. Click "Try it out"
  4. Click "Execute"
  5. View the response

Project Structure ​

api/b3api/
├── src/
│   ├── controllers/       # REST endpoints
│   ├── repositories/      # Data access
│   ├── services/          # Business logic
│   ├── models/            # Data models
│   ├── datasources/       # DB connections
│   ├── knex_migrations/   # Schema migrations
│   ├── application.ts     # App setup
│   └── index.ts           # Entry point
├── dist/                  # Compiled JS
├── node_modules/          # Dependencies
├── package.json           # Dependencies & scripts
└── tsconfig.json          # TypeScript config

Common Development Tasks ​

Creating a New Endpoint ​

Edit or create a controller:

typescript
// src/controllers/product.controller.ts
import { get } from '@loopback/rest';

export class ProductController {
  @get('/products')
  async getProducts(): Promise<Product[]> {
    return this.productRepository.find();
  }
}

Rebuild and the endpoint is available immediately.

Adding Request Validation ​

Use @requestBody() decorator:

typescript
@post('/products')
async createProduct(
  @requestBody({
    content: {
      'application/json': {
        schema: {
          type: 'object',
          required: ['name', 'price'],
          properties: {
            name: { type: 'string' },
            price: { type: 'number' }
          }
        }
      }
    }
  })
  product: Partial<Product>
): Promise<Product> {
  return this.productRepository.create(product);
}

Database Queries ​

Use repository methods:

typescript
// Find all
const tickets = await this.ticketRepository.find();

// Find with filter
const openTickets = await this.ticketRepository.find({
  where: { status: 'open' }
});

// Find by ID
const ticket = await this.ticketRepository.findById(ticketId);

// Create
const newTicket = await this.ticketRepository.create({
  title: 'New Ticket',
  status: 'open'
});

// Update
await this.ticketRepository.updateById(ticketId, {
  status: 'closed'
});

// Delete
await this.ticketRepository.deleteById(ticketId);

Debugging ​

Using the Debugger ​

The API starts with debugger support on port 3001:

  1. Start the API: npm run start
  2. Attach your IDE's debugger to port 3001
  3. Set breakpoints in your TypeScript code

Logging ​

Use the built-in logger:

typescript
import { inject } from '@loopback/core';
import { RestBindings, Request } from '@loopback/rest';

export class ProductController {
  constructor(
    @inject(RestBindings.Http.REQUEST) private request: Request,
  ) {}

  @get('/products')
  async getProducts(): Promise<Product[]> {
    console.log('Fetching products...');
    return this.productRepository.find();
  }
}

Checking Logs ​

Logs appear in the terminal where you started the API:

bash
npm run start
# Server is running at http://localhost:3001
# Try http://localhost:3001/ping

Testing ​

Run Unit Tests ​

bash
npm run test

Run Linting ​

bash
npm run lint

Fix Lint Issues ​

bash
npm run lint:fix

Troubleshooting ​

Port Already in Use ​

If port 3001 is already in use:

bash
# Find and kill the process
lsof -ti:3001 | xargs kill -9

# Or change the port in src/index.ts

Database Connection Errors ​

Verify MySQL is running:

bash
mysql -h mysqldb -P 3306 -u root -pYpp01o#3 lb4 -e "SELECT 1;"

If MySQL is not accessible, check:

  • Is MySQL server running?
  • Are the credentials correct?
  • Is the database created?

Build Errors ​

Clear and reinstall:

bash
rm -rf node_modules dist
npm install
npm run build

Migration Errors ​

Reset migrations (development only):

bash
# Drop all tables (CAREFUL!)
mysql -h mysqldb -u root -pYpp01o#3 lb4 -e "DROP DATABASE lb4; CREATE DATABASE lb4;"

# Re-run migrations
npm run migrate

Next Steps ​

Syneo/Barcoding Documentation

Copyright © 2025