Skip to content
Vendia

Best Practices

Essential guidance for managing API Catalogs effectively.

Using Vendor Specifications

Most API vendors provide OpenAPI or Swagger specifications. Download the specification file directly from the vendor’s documentation or developer portal.

If Specification Exceeds Limits

All tiers have a 5MB file size limit. Free Tier has a 25 operations per catalog limit (operations are API endpoints like GET /users, POST /orders, etc.).

If a vendor’s specification exceeds these limits, you can edit it to include only the operations you need. To use more than 25 operations per catalog, upgrade to Vendia Pro or Enterprise.

Security

Credentials

  • Use least-privilege credentials (read-only if possible)
  • Use short-lived tokens (OAuth, JWT) rather than permanent API keys
  • Rotate credentials regularly
  • Never commit credentials to version control

Vendia Account

  • Enable multi-factor authentication (MFA)
  • Use strong passwords
  • Monitor account activity

Naming Catalogs

Use descriptive names that identify the service and environment:

  • ✓ “Slack Workspace API”
  • ✓ “GitHub API - Production”
  • ✗ “API 1” or “Test”

Include the API version in the catalog name or use the version override field in settings (numeric semantic versioning format: 1.0.0, 2.1.3, etc.).

Environment Configuration

Use the Base URL Override field to point to the correct API environment (staging, production, etc.) if different from the specification’s default.

Testing

Before relying on a catalog in production:

  1. Test with an AI application (Claude, ChatGPT, etc.)
  2. Verify API calls succeed and return expected data
  3. Check for authentication errors

Maintenance

  • Rotate credentials regularly (set calendar reminders)
  • Update specifications when the vendor releases new versions

Next Steps