{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Versioning Fix Design","description":"Official Altegio API documentation for integrating online booking, CRM, scheduling, POS, and business management features into your applications.","siteUrl":"https://developer.alteg.io","lang":"en","keywords":["Altegio API","REST API","online booking API","appointment scheduling API","business management API","CRM integration","POS API"],"image":"/assets/og-image.5c9c342f49e4dd72b96f7a0faf29bb71fab6ff06bbf97cf4b230d6fcc0abcdb3.e746d8a7.jpg","meta":[{"name":"author","content":"Altegio"},{"name":"twitter:card","content":"summary_large_image"},{"name":"twitter:site","content":"@altegio"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-versioning-fix-design","__idx":0},"children":["API Versioning Fix Design"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"problem","__idx":1},"children":["Problem"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Server URL is hardcoded to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.alteg.io/api/v1"]},", causing V2 paths like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/companies/{id}/tags"]}," to resolve incorrectly as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/api/v2/..."]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"solution","__idx":2},"children":["Solution"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Change base URL to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.alteg.io/api"]}," and use explicit version prefixes in all paths."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"changes","__idx":3},"children":["Changes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-server-url","__idx":4},"children":["1. Server URL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Before\nservers:\n  - url: 'https://api.alteg.io/api/v1'\n\n# After\nservers:\n  - url: 'https://api.alteg.io/api'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-v1-paths-120-paths","__idx":5},"children":["2. V1 Paths (~120 paths)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1"]}," prefix to all existing paths:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Before\n'/companies':\n'/auth':\n'/company/{location_id}':\n\n# After\n'/v1/companies':\n'/v1/auth':\n'/v1/company/{location_id}':\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-v2-paths-6-paths","__idx":6},"children":["3. V2 Paths (6 paths)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Remove ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api"]}," prefix:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# Before\n'/api/v2/companies/{location_id}/activities':\n'/api/v2/companies/{company_id}/tags':\n\n# After\n'/v2/companies/{location_id}/activities':\n'/v2/companies/{company_id}/tags':\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-documentation","__idx":7},"children":["4. Documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add versioning section to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# API Versioning\n\nThe API uses URL path versioning. Currently available versions:\n\n- **V1** (`/v1/...`) - Stable, full-featured API\n- **V2** (`/v2/...`) - New endpoints with improved design\n\nBoth versions are production-ready. New features may be released\nin V2 only. V1 endpoints are maintained for backward compatibility.\n\nBase URL: `https://api.alteg.io/api`\n\nExample requests:\n- V1: `GET https://api.alteg.io/api/v1/companies`\n- V2: `GET https://api.alteg.io/api/v2/companies/{id}/tags`\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-text-references","__idx":8},"children":["5. Text References"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update URL mentions in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.alteg.io/api/v1"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.alteg.io/api"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-does-not-change","__idx":9},"children":["What Does NOT Change"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Files in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths/"]}," directory (connected via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Schemas, responses, components"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["operationId values"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Arazzo test files (they reference operationId, not URLs)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validation","__idx":10},"children":["Validation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"make lint        # OpenAPI validation\nmake test-api    # Arazzo fast-check\nmake build-dev   # Build documentation\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"risks","__idx":11},"children":["Risks"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Risk"},"children":["Risk"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mitigation"},"children":["Mitigation"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Break existing spec references"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lint check after changes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arazzo tests fail to find operationId"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["operationId unchanged"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["External systems use spec directly"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Breaking change, internal docs only"]}]}]}]}]}]},"headings":[{"value":"API Versioning Fix Design","id":"api-versioning-fix-design","depth":1},{"value":"Problem","id":"problem","depth":2},{"value":"Solution","id":"solution","depth":2},{"value":"Changes","id":"changes","depth":2},{"value":"1. Server URL","id":"1-server-url","depth":3},{"value":"2. V1 Paths (~120 paths)","id":"2-v1-paths-120-paths","depth":3},{"value":"3. V2 Paths (6 paths)","id":"3-v2-paths-6-paths","depth":3},{"value":"4. Documentation","id":"4-documentation","depth":3},{"value":"5. Text References","id":"5-text-references","depth":3},{"value":"What Does NOT Change","id":"what-does-not-change","depth":2},{"value":"Validation","id":"validation","depth":2},{"value":"Risks","id":"risks","depth":2}],"frontmatter":{"seo":{"title":"API Versioning Fix Design"}},"lastModified":"2026-01-01T13:51:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/plans/2026-01-01-api-versioning-fix-design","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}