Skip to main content

OX Bema - URL Structure & Versioning

Overview​

This document defines the comprehensive URL structure and versioning strategy for OX Agry's corporate website and application ecosystem.

System Architecture​

Corporate Website Ecosystem​

  • Primary Website: Content management and corporate functionality
  • Corporate API: Backend services for the corporate website

App Ecosystem​

  • Multi-version Applications: Historical versions (v1), current production (v2), and development versions (v3+)
  • Independent APIs: Separate backend services for each app version

URL Structure Patterns​

Corporate Website​

ServiceURL PatternExample
Production Websitewww.oxbema.comwww.oxbema.com
Corporate APIapi-www.oxbema.comapi-www.oxbema.com
Corporate Mediamedia-www.oxbema.commedia-www.oxbema.com
Staging Website{env}-v{major}.www.oxbema.comstaging.www.oxbema.com
Staging APIapi-{env}-v{major}-www.oxbema.comapi-staging-www.oxbema.com
Staging Mediamedia-{env}-v{major}-www.oxbema.commedia-staging-www.oxbema.com
Versioned Websitev{major}-{minor}.www.oxbema.comv2-1.www.oxbema.com
Versioned APIapi-v{major}-{minor}-www.oxbema.comapi-v2-1-www.oxbema.com
Versioned Mediamedia-v{major}-{minor}-www.oxbema.commedia-v2-1-www.oxbema.com

App Ecosystem​

ServiceURL PatternExample
App Frontendv{major}-app.oxbema.comv2-app.oxbema.com
App APIapi-v{major}-app.oxbema.comapi-v2-app.oxbema.com
App Mediamedia-v{major}-app.oxbema.commedia-v2-app.oxbema.com
Staging Frontend{env}-v{major}.app.oxbema.comstaging-v2.app.oxbema.com
Staging APIapi-{env}-v{major}-app.oxbema.comapi-staging-v2-app.oxbema.com
Staging Mediamedia-{env}-v{major}-app.oxbema.commedia-staging-v2-app.oxbema.com
Versioned Frontendv{major}-{minor}.app.oxbema.comv2-1.app.oxbema.com
Versioned APIapi-v{major}-{minor}-app.oxbema.comapi-v2-1-app.oxbema.com
Versioned Mediamedia-v{major}-{minor}-app.oxbema.commedia-v2-1-app.oxbema.com

Versioning Strategy​

Version Number Format​

  • Major versions: v1, v2, v3 (breaking changes)
  • Major.Minor versions: v2-1, v3-2 (feature releases)
  • Patch versions: Handled internally, not in DNS

Rationale for Major.Minor in DNS​

Based on industry best practices:

Advantages:

  • Stability: Patch versions (2.1.0 → 2.1.1) don't require DNS changes
  • Client-friendly: Users don't need to update URLs for bug fixes
  • Breaking change boundary: Major.Minor represents the API contract
  • Operational efficiency: Reduces DNS churn

Trade-offs:

  • Less granular: Patch-level clarity is lost in URLs
  • Internal tracking: Need to track exact versions in deployment docs/headers

Environment Strategy​

  • Production: Clean version URLs (v2.app.oxbema.com)
  • Staging: Environment prefix (staging-v2.app.oxbema.com)
  • Feature branches: Specific version tags (v2-1.app.oxbema.com)

Complete URL Examples​

Current Production Setup​

Corporate:
├── www.oxbema.com                       (Corporate website)
├── api-www.oxbema.com                   (Corporate API)
├── media-www.oxbema.com                 (Corporate media)
├── staging.www.oxbema.com               (Corporate staging)
├── api-staging-www.oxbema.com           (Corporate staging API)
├── media-staging-www.oxbema.com         (Corporate staging media)
├── v2-1.www.oxbema.com                  (Versioned corporate website)
├── api-v2-1-www.oxbema.com              (Versioned corporate API)
└── media-v2-1-www.oxbema.com            (Versioned corporate media)

App Ecosystem:
├── v1.app.oxbema.com                    (Legacy app - historical data)
├── api-v1-app.oxbema.com                (Legacy API)
├── media-v1-app.oxbema.com              (Legacy media)
├── v2.app.oxbema.com                    (Current production app)
├── api-v2-app.oxbema.com                (Current production API)
├── media-v2-app.oxbema.com              (Current production media)
├── staging-v2.app.oxbema.com            (Current staging)
├── api-staging-v2-app.oxbema.com        (Current staging API)
├── media-staging-v2-app.oxbema.com      (Current staging media)
├── v3.app.oxbema.com                    (Next version staging)
├── api-staging-v3-app.oxbema.com        (Next version staging API)
├── media-staging-v3-app.oxbema.com      (Next version staging media)
├── v2-1.app.oxbema.com                  (Versioned app release)
├── api-v2-1-app.oxbema.com              (Versioned app API)
└── media-v2-1-app.oxbema.com            (Versioned app media)

User-Friendly Aliases​

app.oxbema.com → v2.app.oxbema.com           (Current production redirect)
api-app.oxbema.com → api-v2-app.oxbema.com          (Corporate API shortcut)
media-app.oxbema.com → media-v2-app.oxbema.com      (Corporate media shortcut)

Design Principles​

1. Consistency​

  • All URLs follow predictable patterns
  • Same hierarchy across corporate and app ecosystems
  • Version indicators in consistent positions

2. Clarity​

  • Service type clearly indicated (www, app, api, media)
  • Version immediately visible
  • Environment explicitly stated when not production

3. Scalability​

  • Easy to add new versions
  • Environment strategy scales with team growth
  • Supports independent deployment cycles

4. User Experience​

  • Clean, professional URLs
  • Shorter URLs for user-facing services
  • Intuitive naming that matches user expectations

5. Technical Considerations​

  • DNS-compliant (hyphens in version numbers)
  • SSL wildcard-friendly
  • CDN and load balancer compatible

Operational Guidelines​

DNS Management​

  • Use hyphens for all separators (DNS compliant and SSL-friendly)
  • Single-level subdomains only (compatible with Cloudflare free plan)
  • Automatic SSL coverage with *.app.oxbema.com, *.www.oxbema.com wildcards
  • Set up health checks for all production URLs

Deployment Strategy​

  • Pin major.minor versions in DNS
  • Handle patch versions through application deployment
  • Use feature flags for gradual rollouts within versions

Documentation Requirements​

  • Maintain API documentation at consistent URLs
  • Version API docs with the same major.minor pattern
  • Include exact patch version in deployment headers

Monitoring​

  • Track traffic patterns across versions
  • Monitor redirect performance
  • Alert on DNS resolution issues

Best Practices Summary​

  1. Keep it simple: Avoid unnecessary redirects or complex nesting
  2. Be consistent: Follow the established patterns across all services
  3. Plan for scale: Consider future versions and services in your structure
  4. User-first: Prioritize clean URLs for user-facing services
  5. Document everything: Maintain clear records of all URL mappings and their purposes

Document Version: 1.0
Last Updated: August 2025
Status: Approved for Implementation