Adding New Services to the Helper Server

This document describes the process for adding new API services to the Helper server using OpenAPI specifications. The workflow consists of three main steps:

1. Generate the service code using an OpenAPI YAML file
2. Register the service manually in config.yaml
3. Develop the service using the available Helper tools

Once these steps are completed, the Helper server will automatically expose the new API when it starts.

---

1. Generating a New Service

New services are generated from an OpenAPI YAML file using the generate.sh script.

Usage

./generate.sh <openapi_yaml> <service_name>

Example

./generate.sh openapi_myservice.yaml myservice

This generates the following structure:

services/myservice/
  ├── controllers/
  ├── models/
  ├── core/        (to be created by the developer)
  └── openapi/openapi.yaml

Note: The generate.sh script does not modify the configuration file. You must register the new service manually in the next step.

---

2. Registering the Service in config.yaml

Each service must be added to the package_paths section in config.yaml.

Example entry

package_paths:
  myservice:
    path: /myservice
    openapi_file: myservice/openapi/openapi.yaml

Field description

Field	Meaning
path	Base URL where the API will be exposed
openapi_file	Relative path from the services/ folder to the OpenAPI file

Once added, the Helper server will automatically load and expose this API on startup.

---

3. Development Tools for New Services

After generating and registering your service, you can start implementing its logic. The Helper provides several utilities to help with this.

---

Database Access (MongoDB)

To access the Mongo database configured in config.yaml:

from db.db import get_mongo

db = get_mongo()

You can then interact with collections:

collection = db.get_col_by_name("my_collection")
result = collection.find_one({})

---

Accessing Dynamic Configuration

Any dynamic or service-specific values should be added to config.yaml. To read them inside your service:

from config import Config

config = Config().get_config()

config is a Python dictionary containing the full contents of config.yaml.

---

Recommended Service Structure

To maintain consistency across services and follow the conventions used in openCAPIF:

• Controllers should only handle routing, validation, and simple response formatting.
• The core logic should be placed inside a dedicated core/ folder.

Recommended folder structure

services/myservice/
  ├── controllers/
  │     └── myservice_controller.py
  ├── core/
  │     └── myservice_core.py
  ├── models/
  └── openapi/openapi.yaml

Example controller using the core layer

from ..core.myservice_core import process_request

def handle_request(body):
    return process_request(body)

This creates a clean separation of concerns and keeps your service easy to maintain.

---

After completing these steps, simply restart the Helper server and your new API will be available automatically.