Skip to main content

API Documentation

Complete API specifications, testing tools, and integration guides for The Villa Life (TVL) Platform.

Quick Start​

Files​

API Specifications​

openapi.yaml

  • OpenAPI 3.0 specification
  • All REST endpoints documented
  • Request/response schemas
  • Authentication requirements
  • Error codes and responses
  • Can be imported into Postman, Swagger UI, or any OpenAPI-compatible tool

Postman Collection​

postman-collection.json

  • Complete API test suite
  • Pre-request scripts for authentication
  • Environment variable usage
  • Example requests for all endpoints
  • Response validation tests

Postman Environments:

Guides​

Practical guides for API development, testing, and integration.

API Testing Guide​

  • Setting up Postman
  • Running automated tests
  • CI/CD integration
  • Load testing with k6

Contract Testing​

  • Consumer-driven contract testing
  • Pact integration
  • Schema validation
  • Backward compatibility

Postman Guide​

  • Importing collections
  • Using environments
  • Writing tests
  • Debugging requests

SDK Generation Guide​

  • Generating TypeScript SDK
  • Generating Python SDK
  • Custom SDK templates
  • Versioning strategy

API Changelog​

  • Breaking changes
  • Deprecations
  • New endpoints
  • Version history

API Versioning​

TVL Platform APIs follow semantic versioning:

  • Base URL: https://api.thevillalife.com/v1
  • Current Version: v1
  • Versioning Strategy: URL-based (/v1/, /v2/)

Authentication​

All API endpoints require authentication via:

  • OAuth 2.0 with Google OIDC
  • Bearer tokens in Authorization header
  • API keys for service-to-service communication

See OpenAPI spec for detailed authentication requirements per endpoint.

Rate Limiting​

  • Default: 100 requests/minute per user
  • Burst: 10 requests/second
  • Headers:
    • X-RateLimit-Limit - Total limit
    • X-RateLimit-Remaining - Remaining requests
    • X-RateLimit-Reset - Reset time (Unix timestamp)

Error Handling​

TVL APIs use RFC 7807 Problem Details format:

{
  "type": "https://api.thevillalife.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid email format",
  "instance": "/api/v1/users/123",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT"
    }
  ]
}

See: API Error Handling Guide

Testing​

Local Testing​

# Import Postman collection and local environment
# Set base_url variable to http://localhost:3000
# Run collection tests

Automated Testing​

# Using Newman (Postman CLI)
newman run postman-collection.json \
  -e postman-environments/postman-env-local.json \
  --reporters cli,json

# Using k6 for load testing
k6 run load-tests/api-load-test.js

SDK Generation​

Generate client SDKs from OpenAPI spec:

# TypeScript
./scripts/generate-typescript-sdk.sh

# Python
./scripts/generate-python-sdk.sh

See: SDK Generation Guide

Contributing​

When adding new endpoints:

  1. Update openapi.yaml with complete specification
  2. Add examples to Postman collection
  3. Write integration tests
  4. Update API changelog
  5. Regenerate SDKs if client-facing

Last Updated: 2025-10-25