Topcoder Group API

Group API built on modern frameworks for managing all group-related Topcoder needs.

Project setup

$ pnpm install

Compile and run the project

# development
$ pnpm run start

# watch mode
$ pnpm run start:dev

# production mode
$ pnpm run start:prod

Database

# run postgres in docker, or other approach
docker run -p 5432:5432  -e POSTGRES_PASSWORD=mysecretpassword postgres:14

export DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"

# run migration
npx prisma migrate dev

# seed data
npx prisma db seed
or
npx prisma migrate reset

# if you modify prisma schema, run migration again
# and it'll ask
# Enter a name for the new migration:
# just provide a good migration name, such as
#- `add_user_table`
#- `update_user_fields`
#- `create_posts_table`
#- `add_email_to_users`
#- `update_foreign_keys`

Data import

• create a .env file mv .env.sample .env
• update the postgres database url in .env file — DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"
• install dependencies pnpm install
• run the prisma migration npx prisma migrate dev
• run the prisma seed npx prisma db seed
• run the project pnpm run start

Test API

• import Postman collection. The files are doc/Group API.postman_collection.json and doc/Group.postman_environment.json
• set env to suit your environment
• run mock api node mock/mock-api.js
• reset seed data pnpm run seed-data
• start app pnpm run start:dev
• generate the token

curl --request POST \
  --url https://auth0proxy.topcoder-dev.com/token \
  --header 'content-type: application/json' \
  --data '{"auth0_url": "https://topcoder-dev.auth0.com/oauth/token", "client_id":"8uHVTW2WHp8BbBPX7J0YTAwgYbYTfjsM","client_secret":"hQXGeKO-cSZ15CLBNRDGZAGRcHWay6PAR_zTQQz4YjdX7QNU7NwGoaa3YuuUYvUv","audience":"https://m2m.topcoder-dev.com/","grant_type":"client_credentials"}'

For a read-only scope M2M token, use:

"client_id":"dgrh9mkk8N6sWsVPFf6JqdVmjjuibowf"
"client_secret":"_6jFqIppsA3u87Tm7mRDXhX_yf8-DC2ooc5f0affjuWoRiLG1ZriHtUsMQgo61qp"

• then you can use Postman to test all apis
• Swagger docs are accessible at http://localhost:3000/api-docs

Downstream Usage

• This service is consumed by multiple Topcoder apps. Below is a quick map of where and how it’s called to help with debugging.

platform-ui

• Admin pages manage groups and memberships using v6 endpoints:
  • List/search groups: GET /v6/groups?page=1&perPage=10000 (optionally filter by name, or by memberId + membershipType=user). See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Fetch group by id: GET /v6/groups/{id} (optional fields query). See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • List group members: GET /v6/groups/{id}/members?page&perPage. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Create group: POST /v6/groups. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Add member: POST /v6/groups/{id}/members with { membershipType: 'user'|'group', memberId }. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Remove member: DELETE /v6/groups/{id}/members/{memberId}. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
• Local dev proxy maps both /v5/groups and /v6/groups to this service on port 3001. See platform-ui/src/config/environments/local.env.ts.

community-app

• Used server-side to expand community metadata group IDs to include descendants (group trees). The code acquires an M2M token and calls the groups service helper, which in turn queries the Groups API for a group’s tree of IDs. See community-app/src/server/services/communities.js and community-app/src/server/services/communities.js.
• Community App requires M2M credentials with access to Groups API for this logic. See community-app/README.md.
• Equivalent v6 endpoint for tree expansion is: GET /v6/groups/{id}?flattenGroupIdTree=true (also supports includeSubGroups, includeParentGroup, oneLevel).

work-manager

• Populates group selectors and filters challenge visibility:
  • Search groups by name for autocomplete: GET /v6/groups?name={query}&perPage={large}. See work-manager/src/components/ChallengeEditor/Groups-Field/index.js.
  • Load current user’s groups when creating/editing a challenge: GET /v6/groups?membershipType=user&memberId={tcUserId}&perPage={large}. See work-manager/src/actions/challenges.js.
  • Fetch group detail by id: GET /v6/groups/{id}. See work-manager/src/services/challenges.js.
• API base configuration points to v6 in dev/local and v5 in prod (for backward compatibility):
  • Dev: work-manager/config/constants/development.js.
  • Local: work-manager/config/constants/local.js and work-manager/config/constants/local.js.