483 lines
14 KiB
Markdown
483 lines
14 KiB
Markdown
# TODO: Migrate from v2 API to GraphQL API
|
|
|
|
**Status**: 🔴 Not Started
|
|
**Priority**: HIGH
|
|
**Estimated Effort**: 2-3 weeks
|
|
**Last Updated**: October 23, 2025
|
|
|
|
## Overview
|
|
|
|
Currently, the tilbudsgiveren application uses the **v2 REST API** for Ordrestyring integration. We need to migrate all API calls to the new **GraphQL API** at `https://graphql.ordrestyring.dk/graphql`.
|
|
|
|
## Benefits of Migration
|
|
|
|
✅ **Single endpoint** - No more managing multiple REST endpoints
|
|
✅ **Efficient data fetching** - Request only the fields you need
|
|
✅ **Type safety** - GraphQL schema provides strong typing
|
|
✅ **Better error handling** - Structured error responses
|
|
✅ **Reduced over/under-fetching** - Get exactly what you need
|
|
✅ **Real-time capabilities** - GraphQL subscriptions for live updates
|
|
✅ **Better documentation** - Self-documenting API via introspection
|
|
|
|
## Current State
|
|
|
|
### API Scripts Available
|
|
Located in `/home/w34078/scripts/apitest/`:
|
|
- **255 Query Scripts** (read-only operations) - ✅ Safe to integrate immediately
|
|
- **311 Mutation Scripts** (write operations) - ⚠️ Requires careful integration
|
|
- **144 Output Examples** - Real API responses for testing
|
|
- **565/566 Endpoints documented** (99.8% coverage)
|
|
|
|
### Documentation
|
|
- `API_INTEGRATION_GUIDE.md` - Complete integration guide
|
|
- `BATCH_*_SUMMARY.md` - Batch documentation files
|
|
- All scripts have `--help` documentation
|
|
|
|
## Migration Plan
|
|
|
|
### Phase 1: Setup & Infrastructure (Week 1)
|
|
|
|
#### 1.1 Backend Setup
|
|
- [ ] Install GraphQL client library (`graphql-request` or `apollo-client`)
|
|
- [ ] Create GraphQL client wrapper in `backend/src/graphql/client.js`
|
|
- [ ] Set up authentication with API key from environment variables
|
|
- [ ] Create error handling middleware for GraphQL responses
|
|
|
|
**Example**:
|
|
```javascript
|
|
// backend/src/graphql/client.js
|
|
const { GraphQLClient } = require('graphql-request');
|
|
|
|
const client = new GraphQLClient('https://graphql.ordrestyring.dk/graphql', {
|
|
headers: {
|
|
authorization: `Bearer ${process.env.ORDRESTYRING_API_KEY}`,
|
|
},
|
|
});
|
|
|
|
module.exports = client;
|
|
```
|
|
|
|
#### 1.2 Environment Configuration
|
|
- [ ] Add `ORDRESTYRING_API_KEY` to `.env` file
|
|
- [ ] Add `GRAPHQL_ENDPOINT` to `.env` file
|
|
- [ ] Update deployment scripts to include new env vars
|
|
- [ ] Document API key rotation procedure
|
|
|
|
**Files to update**:
|
|
- `.env`
|
|
- `.env.example`
|
|
- `README.md`
|
|
- Deployment scripts
|
|
|
|
### Phase 2: Query Migration (Week 1-2)
|
|
|
|
Migrate all **read-only queries first** - these are safe to integrate immediately.
|
|
|
|
#### 2.1 Core Business Queries (High Priority)
|
|
|
|
##### Cases API
|
|
- [ ] Migrate `GET /api/cases` → GraphQL `cases` query
|
|
- [ ] Migrate `GET /api/cases/:id` → GraphQL `case(id: $id)` query
|
|
- [ ] Migrate case activities, statuses, types, templates queries
|
|
- [ ] Update React components to use new endpoints
|
|
|
|
**Current**: `/api/customer-projects/`
|
|
**New**: GraphQL queries from `curl_cases.sh`, `curl_case_activities.sh`, etc.
|
|
|
|
**Files to update**:
|
|
- `backend/routes/customerProjects.js`
|
|
- `frontend/src/api/customerProjectsAPI.js`
|
|
- `frontend/src/components/ProjectList.jsx`
|
|
- `frontend/src/components/ProjectDetails.jsx`
|
|
|
|
##### Customers API
|
|
- [ ] Migrate `GET /api/customers` → GraphQL `customers` query
|
|
- [ ] Migrate `GET /api/customers/:id` → GraphQL `customer(id: $id)` query
|
|
- [ ] Migrate contact persons, categories queries
|
|
- [ ] Update customer selection components
|
|
|
|
**Files to update**:
|
|
- `backend/routes/customers.js` (if exists)
|
|
- `frontend/src/api/customersAPI.js`
|
|
- Customer selection components
|
|
|
|
##### Offers API
|
|
- [ ] Migrate offers queries
|
|
- [ ] Migrate offer lines, statuses, types queries
|
|
- [ ] Update quote/offer components
|
|
|
|
##### Products API
|
|
- [ ] Migrate products queries
|
|
- [ ] Migrate materials, suppliers queries
|
|
- [ ] Update material selection components
|
|
|
|
#### 2.2 Supporting Queries (Medium Priority)
|
|
|
|
- [ ] Invoices (sales, creditor, drafts)
|
|
- [ ] Finance agreements and contracts
|
|
- [ ] Services and installations
|
|
- [ ] Hours and time tracking
|
|
- [ ] Documentation and files
|
|
|
|
#### 2.3 Configuration Queries (Low Priority)
|
|
|
|
- [ ] Settings and preferences
|
|
- [ ] VAT types, payment terms
|
|
- [ ] Discount groups, hour types
|
|
- [ ] User and department data
|
|
|
|
### Phase 3: Safe Mutations (Week 2)
|
|
|
|
Integrate **safe mutations** that don't modify critical data:
|
|
|
|
- [ ] `markMessageAsRead` - Mark notifications as read (idempotent)
|
|
- [ ] `setNamedPreference` - User preferences (safe)
|
|
- [ ] `sendCaseViaEmail` - Send notifications (with confirmation)
|
|
- [ ] `sendOfferViaEmail` - Send offers (with confirmation)
|
|
- [ ] `approveScheme` - Approve schemes (with validation)
|
|
|
|
**Safety measures**:
|
|
- ✅ All operations are idempotent or have user confirmation
|
|
- ✅ No data deletion or modification of critical records
|
|
- ✅ Easy rollback if needed
|
|
|
|
**Files to update**:
|
|
- Backend mutation services
|
|
- Frontend action handlers
|
|
- Add confirmation dialogs for email sends
|
|
|
|
### Phase 4: Update Mutations (Week 3)
|
|
|
|
⚠️ **REQUIRES TEST ENVIRONMENT FIRST**
|
|
|
|
Integrate **update mutations** with proper validation:
|
|
|
|
#### 4.1 Test Environment Setup
|
|
- [ ] Create test database snapshot
|
|
- [ ] Set up staging environment with test GraphQL endpoint
|
|
- [ ] Implement rollback procedures
|
|
- [ ] Create audit logging for all mutations
|
|
|
|
#### 4.2 Core Update Mutations
|
|
- [ ] `updateCase` - Update case details
|
|
- [ ] `updateCustomer` - Update customer information
|
|
- [ ] `updateOffer` - Update offer details
|
|
- [ ] `updateProduct` - Update product information
|
|
- [ ] `updateInvoice` - Update invoice data
|
|
|
|
**Safety requirements**:
|
|
- ✅ Input validation on backend
|
|
- ✅ User authentication/authorization
|
|
- ✅ Audit trail of all changes
|
|
- ✅ Rollback capability
|
|
- ✅ Test in staging before production
|
|
|
|
### Phase 5: Create/Delete Operations (Week 4+)
|
|
|
|
🔴 **HIGH RISK - IMPLEMENT LAST**
|
|
|
|
**Critical requirements before implementation**:
|
|
1. ✅ Test environment mandatory
|
|
2. ✅ Rollback procedures documented and tested
|
|
3. ✅ User confirmation dialogs for all operations
|
|
4. ✅ Audit logging with user tracking
|
|
5. ✅ Database backup before execution
|
|
6. ✅ Soft delete implementation (mark as deleted, don't remove)
|
|
|
|
#### 5.1 Create Mutations
|
|
- [ ] `createCase` - Create new cases
|
|
- [ ] `createCustomer` - Create new customers
|
|
- [ ] `createOffer` - Create new offers
|
|
- [ ] `createProduct` - Create new products
|
|
- [ ] `createInvoice` - Create new invoices
|
|
|
|
#### 5.2 Delete Mutations (LAST)
|
|
- [ ] Implement soft delete strategy
|
|
- [ ] `deleteCase` → `archiveCase` (soft delete)
|
|
- [ ] `deleteCustomer` → `anonymizeCustomer` (GDPR compliant)
|
|
- [ ] Add restore functionality
|
|
- [ ] Add bulk operations with careful validation
|
|
|
|
## Code Examples
|
|
|
|
### GraphQL Query Integration
|
|
|
|
**Before** (REST API):
|
|
```javascript
|
|
// frontend/src/api/customerProjectsAPI.js
|
|
export const getProjects = async (page = 1, limit = 20) => {
|
|
const response = await fetch(`/api/customer-projects?page=${page}&limit=${limit}`);
|
|
return response.json();
|
|
};
|
|
```
|
|
|
|
**After** (GraphQL):
|
|
```javascript
|
|
// frontend/src/api/customerProjectsAPI.js
|
|
import { request } from '../utils/graphqlClient';
|
|
|
|
export const getProjects = async (page = 1, limit = 20) => {
|
|
const query = `
|
|
query GetCases($pagination: Pagination) {
|
|
cases(pagination: $pagination) {
|
|
items {
|
|
id
|
|
caseNumber
|
|
customer { id name }
|
|
status { id name }
|
|
createdAt
|
|
}
|
|
totalCount
|
|
}
|
|
}
|
|
`;
|
|
|
|
const data = await request(query, {
|
|
pagination: { page, limit }
|
|
});
|
|
|
|
return data.cases;
|
|
};
|
|
```
|
|
|
|
### GraphQL Mutation Integration
|
|
|
|
**Before** (REST API):
|
|
```javascript
|
|
export const updateProject = async (projectId, projectData) => {
|
|
const response = await fetch(`/api/customer-projects/${projectId}`, {
|
|
method: 'PUT',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify(projectData)
|
|
});
|
|
return response.json();
|
|
};
|
|
```
|
|
|
|
**After** (GraphQL):
|
|
```javascript
|
|
export const updateProject = async (caseId, caseInput) => {
|
|
const mutation = `
|
|
mutation UpdateCase($id: Int!, $input: CaseInput!) {
|
|
updateCase(id: $id, input: $input) {
|
|
id
|
|
caseNumber
|
|
updatedAt
|
|
}
|
|
}
|
|
`;
|
|
|
|
const data = await request(mutation, {
|
|
id: parseInt(caseId),
|
|
input: caseInput
|
|
});
|
|
|
|
return data.updateCase;
|
|
};
|
|
```
|
|
|
|
## Files That Need Migration
|
|
|
|
### Backend Files
|
|
- [ ] `backend/routes/customerProjects.js` - All case/project endpoints
|
|
- [ ] `backend/routes/customers.js` - Customer endpoints (if exists)
|
|
- [ ] `backend/routes/offers.js` - Offer endpoints (if exists)
|
|
- [ ] `backend/routes/products.js` - Product endpoints (if exists)
|
|
- [ ] `backend/services/*Service.js` - All service files that call v2 API
|
|
|
|
### Frontend Files
|
|
- [ ] `frontend/src/api/customerProjectsAPI.js`
|
|
- [ ] `frontend/src/api/customersAPI.js`
|
|
- [ ] `frontend/src/api/offersAPI.js`
|
|
- [ ] `frontend/src/api/productsAPI.js`
|
|
- [ ] All components that directly call API functions
|
|
|
|
### Configuration Files
|
|
- [ ] `.env` - Add GraphQL endpoint and API key
|
|
- [ ] `.env.example` - Document required env vars
|
|
- [ ] `README.md` - Update API documentation
|
|
- [ ] Deployment scripts - Include new env vars
|
|
|
|
## Testing Strategy
|
|
|
|
### 1. Query Testing (Safe)
|
|
✅ All 255 queries already tested in production
|
|
✅ 144 output files available as test fixtures
|
|
✅ Can integrate immediately
|
|
|
|
**Test approach**:
|
|
1. Create test suite using output files as expected results
|
|
2. Run GraphQL queries and compare with v2 API responses
|
|
3. Validate data structure matches frontend expectations
|
|
4. Check pagination, filtering, sorting
|
|
|
|
### 2. Mutation Testing (Requires Staging)
|
|
|
|
**Test environment setup**:
|
|
1. Clone production database to staging
|
|
2. Point staging app to test GraphQL endpoint
|
|
3. Test all mutations with dummy data
|
|
4. Validate rollback procedures
|
|
|
|
**Test checklist**:
|
|
- [ ] Test create operations
|
|
- [ ] Test update operations
|
|
- [ ] Test delete operations (soft delete)
|
|
- [ ] Test bulk operations
|
|
- [ ] Test error handling
|
|
- [ ] Test validation
|
|
- [ ] Test rollback procedures
|
|
|
|
### 3. Integration Testing
|
|
|
|
- [ ] Test complete user workflows (create → update → delete)
|
|
- [ ] Test concurrent operations
|
|
- [ ] Test error scenarios (network failures, timeouts)
|
|
- [ ] Test authentication failures
|
|
- [ ] Test rate limiting
|
|
- [ ] Performance testing (compare with v2 API)
|
|
|
|
## Rollback Plan
|
|
|
|
If migration fails or introduces bugs:
|
|
|
|
1. **Immediate Rollback** (< 5 minutes)
|
|
- Keep v2 API endpoints active during migration
|
|
- Use feature flags to toggle between v2/GraphQL
|
|
- Can switch back via environment variable
|
|
|
|
2. **Gradual Migration**
|
|
- Migrate one feature at a time
|
|
- Keep both APIs running in parallel
|
|
- Monitor error rates and performance
|
|
- Roll back individual features if needed
|
|
|
|
3. **Data Rollback**
|
|
- Database snapshots before write operations
|
|
- Audit log for all mutations
|
|
- Restore procedures documented and tested
|
|
|
|
## Performance Considerations
|
|
|
|
### Optimization Strategies
|
|
- [ ] Use pagination for large datasets (default: 20 items per page)
|
|
- [ ] Implement caching for frequently accessed data
|
|
- [ ] Use GraphQL field selection (only request needed fields)
|
|
- [ ] Batch operations where possible (bulkUpdate* mutations)
|
|
- [ ] Monitor API rate limits and implement throttling
|
|
|
|
### Monitoring
|
|
- [ ] Track API response times
|
|
- [ ] Monitor error rates
|
|
- [ ] Alert on rate limit approaches
|
|
- [ ] Log slow queries (> 1 second)
|
|
|
|
## Security Checklist
|
|
|
|
- [ ] API key stored in environment variables (never in code)
|
|
- [ ] Backend validates all user input
|
|
- [ ] HTTPS only for API communication
|
|
- [ ] Implement user authentication/authorization
|
|
- [ ] Rate limiting on backend
|
|
- [ ] Audit logging for mutations
|
|
- [ ] User confirmation for dangerous operations
|
|
- [ ] SQL injection prevention (parameterized queries)
|
|
- [ ] XSS prevention (input sanitization)
|
|
|
|
## Resources
|
|
|
|
### Documentation
|
|
- **Main Guide**: `apitest/API_INTEGRATION_GUIDE.md`
|
|
- **Scripts Location**: `/home/w34078/scripts/apitest/examples/`
|
|
- **Output Examples**: `/home/w34078/scripts/apitest/examples/output/`
|
|
- **GraphQL Endpoint**: `https://graphql.ordrestyring.dk/graphql`
|
|
- **API Key**: Stored in environment variables
|
|
|
|
### Available Scripts by Category
|
|
|
|
#### Safe Queries (255 scripts)
|
|
- `curl_cases.sh`, `curl_customers.sh`, `curl_offers.sh`, `curl_products.sh`
|
|
- `curl_invoices.sh`, `curl_users.sh`, `curl_departments.sh`
|
|
- See `API_INTEGRATION_GUIDE.md` for complete list
|
|
|
|
#### Safe Mutations (24 scripts)
|
|
- `mutation_mark_message_as_read.sh`
|
|
- `mutation_set_named_preference.sh`
|
|
- `mutation_send_*_via_email.sh` (7 scripts)
|
|
- `mutation_approve_scheme.sh`
|
|
|
|
#### Update Mutations (78 scripts)
|
|
- `mutation_update_case.sh`
|
|
- `mutation_update_customer.sh`
|
|
- `mutation_update_offer.sh`
|
|
- See `BATCHES_14_15_SUMMARY.md`
|
|
|
|
#### Create/Delete Mutations (208 scripts)
|
|
- `mutation_create_*.sh` (75 scripts)
|
|
- `mutation_delete_*.sh` (59 scripts)
|
|
- See `BATCHES_16_22_SUMMARY.md`
|
|
|
|
## Progress Tracking
|
|
|
|
### Week 1
|
|
- [ ] Backend GraphQL client setup
|
|
- [ ] Environment configuration
|
|
- [ ] Core business queries migration (cases, customers)
|
|
- [ ] Test query integration
|
|
|
|
### Week 2
|
|
- [ ] Remaining query migrations (offers, products, invoices)
|
|
- [ ] Configuration queries migration
|
|
- [ ] Safe mutations integration
|
|
- [ ] Frontend component updates
|
|
|
|
### Week 3
|
|
- [ ] Test environment setup
|
|
- [ ] Update mutations integration
|
|
- [ ] Validation and error handling
|
|
- [ ] Audit logging implementation
|
|
|
|
### Week 4+
|
|
- [ ] Create mutations (with caution)
|
|
- [ ] Soft delete implementation
|
|
- [ ] Final testing and validation
|
|
- [ ] Production deployment
|
|
- [ ] Monitor and optimize
|
|
|
|
## Success Criteria
|
|
|
|
✅ All query endpoints migrated to GraphQL
|
|
✅ Zero data loss during migration
|
|
✅ Performance equal or better than v2 API
|
|
✅ Error rates < 0.1%
|
|
✅ All mutations properly validated
|
|
✅ Audit logging in place
|
|
✅ Rollback procedures tested
|
|
✅ Documentation updated
|
|
✅ Team trained on new API
|
|
|
|
## Notes
|
|
|
|
- Current API key: `<ORDRESTYRING_API_TOKEN>` (rotate after migration)
|
|
- GraphQL endpoint: `https://graphql.ordrestyring.dk/graphql`
|
|
- 565/566 endpoints available (99.8% coverage)
|
|
- All scripts have `--help` documentation
|
|
- 144 output examples available for testing
|
|
|
|
## Next Steps
|
|
|
|
1. **Review this TODO** with team
|
|
2. **Prioritize** which endpoints to migrate first
|
|
3. **Set up** GraphQL client in backend
|
|
4. **Start** with safe query migrations
|
|
5. **Test thoroughly** before production
|
|
6. **Monitor** closely after deployment
|
|
|
|
---
|
|
|
|
**Created**: October 23, 2025
|
|
**Last Updated**: October 23, 2025
|
|
**Assigned To**: Development Team
|
|
**Dependencies**: API_INTEGRATION_GUIDE.md, apitest scripts
|
|
**Related**: ORDRESTYRING_DATABASE_SYSTEM.md
|