Response Summary Config

Overview

This guide outlines the steps for configuring and managing response summary configurations within the hv-api-config and hv-api-config-dev repositories. It's intended for teams working on API configuration updates and deployments.

Prerequisites

• Access to the GitLab repository: hv-central-config
• Understanding of S3 bucket structures:
  • Prod Bucket: hv-api-config
  • Dev Bucket: hv-api-config-dev
• Familiarity with API configuration structures and middleware updates.

Purpose & use case

This process aims to:

• Standardise API response summary configurations.
• Organise configurations per product and endpoint.
• Ensure a smooth transition to new configurations while maintaining backward compatibility.

Who is this for? Teams working on API response summary configurations.

When should this be used? When updating or adding new configurations to the API response summary repository.

Step-by-step guide

1. Setting up — config repository changes

1. Create a product folder

   • Inside response-summary-config/, create a folder named after your product (e.g., thomas).
   • This folder stores all related configurations.

2. Create endpoint folders

   • For each API endpoint, create a corresponding folder.
   • Example: /v1/readId → v1_readid
   • Use lowercase and replace slashes with underscores.
   • Add at least a default.json file in each folder.

3. Create a deprecated folder

   • Inside response-summary-config/{product}/, create a deprecated folder.
   • Move all existing response-summary configuration files into this folder.

4. Sync with the new bucket — mandatory unless not releasing changes immediately.

   • Ensure your pipeline updates both the current and new bucket during the transition period.

2. How it works

Merging changes

When an MR is merged into the main branch, a file named response_summary.json is generated and pushed to:

• Prod: s3://hv-api-config/response-summary-config/{product}/master_configs/
• Dev: s3://hv-api-config-dev/response-summary-config/{product}/master_configs/

Code changes

1. Upgrade middleware

   • Upgrade results-workflow middleware to version v2.0.2.
   • Reference: Middleware v2.0.2

2. Update configuration logic

   • Replace outdated configuration logic with the latest standard.
   • Use RESPONSE_SUMMARY_CONFIG_PATH as response-summary-config/{product}/master_configs/response_summary.json.

3. End-to-end testing

   • Ensure all changes are tested and validated before deployment.

3. Common updates & fixes

1. Order of configuration selection (fallback order):

   • appid_workflowid.json from the API folder
   • appid.json from the API folder
   • appid.json from the deprecated folder
   • default_{version}.json from the API folder
   • default.json from the API folder
   • default.json from the deprecated folder

2. Deprecated folder guidelines:

   • Contains the current configurations as of Feb 2025.
   • No new configs should be added here after migration.
   • New configurations should be added only to respective endpoint-specific folders.

3. Versioned default configurations:

   • Previously, a single default.json was used, making modifications difficult.
   • Now, multiple versions (e.g., default_v1.json, default_v2.json) can coexist.
   • To specify a version, set the header defaultSummaryVersion: v1.

Deep dive

Core concepts

• Product-based folder structure — each product maintains its own configuration hierarchy.
• Endpoint-specific configurations — prevents interference between different API endpoints.
• Deprecation handling — ensures smooth transition without disrupting existing integrations.

Technical details & workflows

• Pipeline synchronisation: configuration updates must be pushed to both production and development buckets during the transition phase.
• Middleware versioning: ensure compatibility with results-workflow v2.0.2.
• Header-based config selection: allows dynamically selecting the appropriate default configuration version.

Common updates & fixes

• Misplaced configurations:
  • Ensure new configurations are placed in endpoint-specific folders.
  • Do not add new configs to the deprecated folder.
• Pipeline failures:
  • Validate S3 paths and permissions before pushing updates.
  • Ensure the pipeline updates both buckets during migration.
• Backward compatibility issues:
  • Use versioned defaults to avoid breaking existing integrations.
  • Test changes in dev before rolling out to prod.