Topcoder Learning Paths API

This microservice provides access to and interaction with Topcoder Academy learning path certification and course content.

Devlopment status

Deployment status

Dev: Prod:

Swagger definition

• TBD

Intended use

• Production API

Related repos

• Frontend App

Prerequisites

• NodeJS (v16)
• DynamoDB
• Docker
• Docker Compose

Configuration

Configuration for the application is at config/default.js. The following parameters can be set in config files or in env variables:

• READONLY: sets the API in read-only mode. POST/PUT/PATCH/DELETE operations will return 403 Forbidden
• LOG_LEVEL: the log level, default is 'debug'
• PORT: the server port, default is 3000
• AUTH_SECRET: The authorization secret used during token verification.
• VALID_ISSUERS: The valid issuer of tokens.
• AUTH0_URL: AUTH0 URL, used to get M2M token
• AUTH0_PROXY_SERVER_URL: AUTH0 proxy server URL, used to get M2M token
• AUTH0_AUDIENCE: AUTH0 audience, used to get M2M token
• TOKEN_CACHE_TIME: AUTH0 token cache time, used to get M2M token
• AUTH0_CLIENT_ID: AUTH0 client id, used to get M2M token
• AUTH0_CLIENT_SECRET: AUTH0 client secret, used to get M2M token
• AMAZON.AWS_ACCESS_KEY_ID: The Amazon certificate key to use when connecting. Use local dynamodb you can set fake value
• AMAZON.AWS_SECRET_ACCESS_KEY: The Amazon certificate access key to use when connecting. Use local dynamodb you can set fake value
• AMAZON.AWS_REGION: The Amazon certificate region to use when connecting. Use local dynamodb you can set fake value
• AMAZON.IS_LOCAL_DB: Use Amazon DynamoDB Local or server
• AMAZON.DYNAMODB_URL: The local url if using Amazon DynamoDB Local
• HEALTH_CHECK_TIMEOUT: health check timeout in milliseconds
• SCOPES: the configurable M2M token scopes, refer config/default.js for more details
• M2M_AUDIT_HANDLE: the audit name used when perform create/update operation using M2M token

You can find sample .env files inside the /docs directory.

Available commands

1. Drop/delete DynamoDB tables: npm run drop-tables
2. Create DynamoDB tables: npm run create-tables
3. Seed/Insert data into DynamoDB tables: npm run seed-tables
4. Initialize/Clear database in default environment: npm run init-db
5. View table data in default environment: npm run view-data <ModelName>, ModelName can be Certification, Course, or LearningResourceProvider
6. Start all the depending services for local deployment: npm run services:up
7. Stop all the depending services for local deployment: npm run services:down
8. Check the logs of all the depending services for local deployment: npm run services:logs
9. Initialize the local environments: npm run local:init
10. Reset the local environments: npm run local:reset

Notes

• The seed data are located in src/scripts/seed

Local Deployment

0. Make sure to use Node v16+ -- check with command node -v. We recommend using NVM to quickly switch to the right version specified in the included .nvmrc file:

   nvm use

1. 📦 Install npm dependencies

   npm install

2. ⚙ Local config
   In the learning-paths-api root directory create an .env file with the following environment variables. Values for Auth0 config should be shared with you on the forum.
   

   # Auth0 config
   AUTH0_URL=
   AUTH0_PROXY_SERVER_URL=
   AUTH0_AUDIENCE=
   AUTH0_CLIENT_ID=
   AUTH0_CLIENT_SECRET=
   
   # Locally deployed services (via docker-compose)
   IS_LOCAL_DB=true
   DYNAMODB_URL=http://localhost:8000

   • Values from this file would be automatically used by many npm commands.
   • ⚠️ Never commit this file or its copy to the repository!

3. 🚢 Use docker-compose to start the services required to run the API locally (DynamoDB).

   npm run services:up

4. ♻ Create empty DynamoDB tables.

   npm run create-tables
   # Use `npm run drop-tables` to drop tables.

5. ♻ Initialize the local database.

   npm run local:init

   This command will do 2 things:

• Initialize the database by deleting all the existing records.
• Seed the database with data from the JSON seed files

7. 🚀 Start the learning paths API.

   npm start

   The Topcoder Learning Paths API will be served on http://localhost:3000
   To start with ExpressJS debug logging turned on, run npm start:debug.

Production deployment

• TBD

Running tests

Configuration

Test configuration is at config/test.js. You don't need to change them. The following test parameters can be set in config file or in env variables:

• ADMIN_TOKEN: admin token
• COPILOT_TOKEN: copilot token
• USER_TOKEN: user token
• EXPIRED_TOKEN: expired token
• INVALID_TOKEN: invalid token
• M2M_FULL_ACCESS_TOKEN: M2M full access token
• M2M_READ_ACCESS_TOKEN: M2M read access token
• M2M_UPDATE_ACCESS_TOKEN: M2M update (including 'delete') access token

Prepare

• Start Local services in docker.
• Create DynamoDB tables.
• Various config parameters should be properly set.

Seeding db data is not needed.

Running unit tests

To run unit tests alone

npm run test

To run unit tests with coverage report

npm run test:cov

Running integration tests

To run integration tests alone

npm run e2e

To run integration tests with coverage report

npm run e2e:cov

Verification

Refer to the verification document Verification.md

Utilities

Several utilities exist to support this API. Read more about them on their READMEs.

Completed Certificate Sharing

Course Generator

MongoDB Trigger Handler

Notes

Security update runtime requirements

The ECS API uses Node.js 26 and pnpm 11.15.1. Run pnpm install --frozen-lockfile with the committed workspace settings and tools directory. The production image uses maintained Alpine Node/OpenSSL packages, runs as UID 10001, and excludes development tools and independent Lambda dependency trees.

The pinned shared authentication/BUS client requires exact VALID_ISSUERS, JWT_AUDIENCE for RSA user tokens, and AUTH0_AUDIENCE for machine tokens. Legacy HMAC user tokens require an explicit AUTH_SECRET of at least 32 bytes. Supply the existing AUTH0 client credentials and endpoint for outbound requests. Route role/scope checks and public-route behavior are preserved. Run pnpm run test:security for local HTTP authentication and token/BUS integration tests, and pnpm run test:dependency-compat for legacy matcher/glob compatibility.

Independent utility manifests retain their own lockfiles and AWS-supported runtimes. The certificate-image Lambda now uses Node 22 with bundled Chromium/Puppeteer, replacing the external Chromium layer. Its deploy script uploads the larger archive through S3 and places the handler at the archive root. Run npm run test:security in that Lambda on Linux to test actual screenshots, or in the Mongo trigger utility to test authenticated lesson updates. Live AWS/database tests and deployments are separate from these local checks.