Example 5: API Integration
Specify technical requirements clearly
Poor Specification
E-commerce Integration
Connect our online store with Odoo. Need to sync products, orders, and customers.
Requirements:
- Two-way sync
- Real-time updates
- Handle errors gracefully
- Map fields correctly
- Support high volume
- Maintain data integrity
- Provide sync status
Should work with our Shopify store and not cause any downtime. Performance is critical during sales periods.
Need proper security and monitoring.
Connect our online store with Odoo. Need to sync products, orders, and customers.
Requirements:
- Two-way sync
- Real-time updates
- Handle errors gracefully
- Map fields correctly
- Support high volume
- Maintain data integrity
- Provide sync status
Should work with our Shopify store and not cause any downtime. Performance is critical during sales periods.
Need proper security and monitoring.
❌ Missing details:
- No API endpoints specified
- "Real-time" not defined
- Volume numbers missing
- Field mapping unclear
- Error handling vague
Better Specification
Shopify-Odoo Integration
Sync Requirements:
Products: Shopify → Odoo (daily, 2AM UTC)
Inventory: Odoo → Shopify (every 15 min)
Orders: Shopify → Odoo (webhook, <30 sec)
Customers: Bi-directional (on change)
Technical Specs:
- Shopify Admin API 2024-01
- Auth: Private app with specific scopes
- Rate limit: 2 requests/second
- Batch: 250 products per call
- Volume: 10K products, 500 orders/day
Field Mapping:
Shopify.title → Odoo.name
Shopify.variant.sku → Odoo.default_code
Shopify.variant.price → Odoo.list_price
Error Handling:
- Retry 3x with exponential backoff
- Log failures to error_sync table
- Email alert if >50 failures/hour
Sync Requirements:
Products: Shopify → Odoo (daily, 2AM UTC)
Inventory: Odoo → Shopify (every 15 min)
Orders: Shopify → Odoo (webhook, <30 sec)
Customers: Bi-directional (on change)
Technical Specs:
- Shopify Admin API 2024-01
- Auth: Private app with specific scopes
- Rate limit: 2 requests/second
- Batch: 250 products per call
- Volume: 10K products, 500 orders/day
Field Mapping:
Shopify.title → Odoo.name
Shopify.variant.sku → Odoo.default_code
Shopify.variant.price → Odoo.list_price
Error Handling:
- Retry 3x with exponential backoff
- Log failures to error_sync table
- Email alert if >50 failures/hour
✓ Technical clarity:
- API versions specified
- Exact sync timing
- Volume metrics clear
- Field mapping explicit
- Error strategy defined
🎓 You've Completed the Examples!
Notice the pattern? Better specifications aren't longer - they're more precise.
Every word serves a purpose. Every requirement is testable.