Best Practices

Best practices for integrating with the VibeMap API.

Follow these guidelines to ensure your integration is secure, performant, and maintainable.

1. Optimize with Batch Operations

Whenever you need to create or update more than 3 items, use the operation key in the request body. Batch operations significantly reduce network overhead and ensure atomicity within the batch.

• DON'T: Loop through 50 user stories and make 50 individual POST requests.

• DO: Combine them into a single POST request with operation: "create".

2. Secure Your Tokens

Your Personal Access Token is a powerful key.

• Environment Variables: Always store tokens in environment variables (e.g., .env files for Node.js, GitHub Secrets for CI/CD).

• Minimal Exposure: Only use tokens in server-side code.

• Prefix Checking: Verify that your token starts with vm_ before sending it to ensure you haven't swapped it with another service's key.

3. Handle Relationships Correctly

The VibeMap data model is hierarchical.

• Parent-First: Always create the parent object (Project -> Feature -> User Story) before attempting to create children.

• ID Validation: Cache the IDs returned from creation to use as parent_id values in subsequent requests.

4. Efficient Polling

If you are waiting for AI analysis to complete:

• Avoid Tight Loops: Don't poll the API every 100ms.

• Progressive Backoff: Poll every 2 seconds, then 5, then 10. Most analyses complete within 15-30 seconds.

5. Use the include Flags

To reduce the total number of requests, use the expansion flags provided by the API:

• includeAnalysis=true on Project GET

• includeRelationships=true on Feature GET

• includeCriteria=true on User Story GET

These flags allow you to fetch nested data in a single round-trip.

6. Content-Type Header

Always include Content-Type: application/json in your headers for POST and PUT requests. Omitting this can lead to unexpected 400 errors as the server may fail to parse the body.