Milestone: M2 — Platform and Client Admin | SOW Reference: FR5, INT3 | Requirement Clarity: ✅ Clear | Dev Status: 🟢 Prototyped in POC Moved from docs/requirements/tasks/velocity-registrar-api-integration.md — this is the original detailed implementation breakdown, unmodified below.

M2-02 Velocity Network Registrar API Integration Tasks¶

This document breaks down the implementation tasks for integrating with the Velocity Network Registrar API, which is essential for registering organizations on the REC Verifiable Credentialing Platform.

Implementation Strategy¶

The implementation will follow these steps: 1. Create DTOs for Velocity Network Registrar API requests and responses 2. Implement a service for interacting with the Velocity Network Registrar API 3. Integrate the service with the organization management functionality 4. Add error handling and retry logic 5. Implement logging and monitoring

Current Implementation Status¶

The project currently has:

Organization Entity:
Basic Organization entity with a velocityRegistrarId field
No integration with the Velocity Network Registrar API

Backend Tasks¶

Velocity Network Registrar API DTOs¶

Create app/backend/src/admin/dto/velocity-registrar.dto.ts
Implement RegisterOrganizationRequestDto:
- name (string, required): Organization name
- domain (string, required): Organization domain
- type (string, required): Organization type (e.g., "staffing_company")
- address (object, required): Organization address
- contactEmail (string, required): Contact email
- contactPhone (string, required): Contact phone
- website (string, required): Organization website
Implement RegisterOrganizationResponseDto:
- id (string): Velocity Network organization ID
- status (string): Registration status
- createdAt (string): Creation timestamp
Implement GetOrganizationResponseDto:
- id (string): Velocity Network organization ID
- name (string): Organization name
- domain (string): Organization domain
- type (string): Organization type
- status (string): Organization status
- createdAt (string): Creation timestamp
- updatedAt (string): Last update timestamp
Implement UpdateOrganizationRequestDto:
- name (string, optional): Organization name
- domain (string, optional): Organization domain
- address (object, optional): Organization address
- contactEmail (string, optional): Contact email
- contactPhone (string, optional): Contact phone
- website (string, optional): Organization website
Implement UpdateOrganizationResponseDto:
- id (string): Velocity Network organization ID
- status (string): Update status
- updatedAt (string): Update timestamp

Velocity Network Registrar API Configuration¶

Create app/backend/src/admin/config/velocity-registrar.config.ts
Implement configuration options:
- apiUrl (string): Velocity Network Registrar API URL
- apiKey (string): API key for authentication
- timeout (number): Request timeout in milliseconds
- retryAttempts (number): Number of retry attempts for failed requests
- retryDelay (number): Delay between retry attempts in milliseconds
Load configuration from environment variables:
- VELOCITY_REGISTRAR_API_URL
- VELOCITY_REGISTRAR_API_KEY
- VELOCITY_REGISTRAR_TIMEOUT
- VELOCITY_REGISTRAR_RETRY_ATTEMPTS
- VELOCITY_REGISTRAR_RETRY_DELAY
Update app/backend/.env.example and app/backend/.env.development
Add the required environment variables with example values

Velocity Network Registrar API Service¶

Create app/backend/src/admin/services/velocity-registrar.service.ts
Implement constructor with configuration injection:
- Inject HttpService for making HTTP requests
- Inject ConfigService for accessing configuration
- Inject LoggerService for logging
Implement registerOrganization method:
- Parameters: RegisterOrganizationRequestDto
- Returns: Promise
- Make POST request to /organizations endpoint
- Add proper error handling
- Add retry logic for network errors
- Log request and response
Implement getOrganization method:
- Parameters: string (organization ID)
- Returns: Promise
- Make GET request to /organizations/{id} endpoint
- Add proper error handling
- Add retry logic for network errors
- Log request and response
Implement updateOrganization method:
- Parameters: string (organization ID), UpdateOrganizationRequestDto
- Returns: Promise
- Make PUT request to /organizations/{id} endpoint
- Add proper error handling
- Add retry logic for network errors
- Log request and response
Implement deleteOrganization method:
- Parameters: string (organization ID)
- Returns: Promise
- Make DELETE request to /organizations/{id} endpoint
- Add proper error handling
- Add retry logic for network errors
- Log request and response
Implement private helper methods:
- buildHeaders(): Builds HTTP headers with API key
- handleError(error): Handles and logs errors
- retryStrategy(error, retryCount): Determines if a request should be retried

Integration with Organization Service¶

Update app/backend/src/admin/services/organization.service.ts
Inject VelocityRegistrarService in constructor
Update createOrganization method:
- Call velocityRegistrarService.registerOrganization
- Store the returned Velocity Network organization ID
Update updateOrganization method:
- Call velocityRegistrarService.updateOrganization
- Update the organization in the local database
Update deleteOrganization method:
- Call velocityRegistrarService.deleteOrganization
- Soft delete the organization in the local database

Error Handling and Monitoring¶

Create app/backend/src/admin/exceptions/velocity-registrar.exception.ts
Implement VelocityRegistrarException class:
- Extends HttpException
- Includes error code, message, and details
- Provides methods for creating specific error types:
- createAuthenticationError(): For API key issues
- createNetworkError(): For network connectivity issues
- createValidationError(): For request validation issues
- createResourceNotFoundError(): For non-existent resources
- createServerError(): For Velocity Network server errors
Update app/backend/src/admin/services/velocity-registrar.service.ts
Use VelocityRegistrarException for error handling
Add detailed logging for all API interactions
Implement metrics collection for API calls:
- Success/failure rate
- Response time
- Retry attempts

Unit Tests¶

Create app/backend/src/admin/services/velocity-registrar.service.spec.ts
Test registerOrganization method:
- Success case
- Network error case
- Authentication error case
- Validation error case
- Server error case
Test getOrganization method:
- Success case
- Resource not found case
- Network error case
Test updateOrganization method:
- Success case
- Resource not found case
- Validation error case
Test deleteOrganization method:
- Success case
- Resource not found case

Dependencies & Assumptions¶

Prerequisites¶

The Organization entity must be properly defined
The HttpModule must be available for making HTTP requests
The ConfigModule must be available for accessing configuration
The LoggerService must be available for logging

Cross-team Needs¶

DevOps team needs to provide Velocity Network Registrar API credentials
DevOps team needs to configure environment variables
QA team needs to provide test accounts for the Velocity Network

Implementation Notes¶

API Security:
The API key should be stored securely
All API requests should use HTTPS
API responses should be validated before processing
Error Handling:
All API errors should be properly handled and logged
Retry logic should be implemented for transient errors
Permanent errors should be reported to administrators
Performance Considerations:
API requests should be cached where appropriate
Batch operations should be used where possible
Long-running operations should be executed asynchronously
Testing Requirements:
Unit tests should mock the HTTP service
Integration tests should use a test environment
End-to-end tests should verify the complete registration flow