Step-by-Step Migration

Implementation guide for migrating from Partner API v1 to v2.

Assessment Phase

1. Audit Current Implementation

   • Document v1 endpoints in use
   • Identify data requirements and usage patterns
   • Review integration workflows

2. Evaluate v2 Capabilities

   • Map existing functionality to v2 endpoints
   • Identify endpoints requiring custom implementation
   • Plan adoption of new v2 features

3. Define Migration Timeline

   • Plan the project with Utopi Product team
   • Schedule testing and validation phases

Preparation Phase

Step 0: Request v2 Access and Resources

Before beginning implementation, request the necessary v2 resources:

1. Request v2 Sandbox Access

   • Contact your technical contact to request v2 sandbox site access
   • Receive v2 sandbox SiteId for development and testing
   • Use the production sandbox environment with realistic dummy data

2. Request ID Mapping Files (if needed)

   • If migrating many spaces, request mapping files containing:
     • spaceId → spaceUuid mappings
     • floorId → floorUuid mappings
     • buildingId → buildingUuid mappings
     • siteId → siteUuid mappings

3. Request Production SiteIds

   • Identify which production sites need v2 access
   • Request production SiteId values for your target sites through your technical contact
   • These will be provided after successful sandbox testing

Step 1: Request Additional Endpoints

For endpoints not yet available in v2:

1. Identify Required Endpoints from the Endpoint Comparison page
2. Document Use Cases with data usage patterns
3. Contact your technical contact with:
   • Required endpoint list
   • Your migration timeline
   • Use case description
   • Expected request volume

Implementation Phase

Step 2: Update Base URL and Authentication

v1 Configuration:

const baseURL = "https://apim.utopi.io/v1"; // or "https://partner-api.utopi.io/v1"

// v1 authentication
const headers = {
  Authorization: "Bearer YOUR_V1_ACCESS_TOKEN",
  TenantId: "YOUR_TENANT_ID", // GUID format
};

v2 Configuration:

const baseURL = "https://partner-api.utopi.io/v2";

// v2 authentication
const headers = {
  Authorization: "Bearer YOUR_V2_ACCESS_TOKEN",
  SiteId: "YOUR_SITE_ID", // GUID format
};

Authentication Changes:

• Identity Provider - Different providers for v1 and v2, both using OAuth 2.0 client credentials
• Token Endpoints - New authentication URLs provided during v2 onboarding
• Token Lifespan - Reduced from 24 hours to 60 minutes
• Access Control - Site-level permissions via SiteId header replace tenant-level TenantId
• Flow Consistency - Bearer token pattern remains unchanged

Step 3: Map Integer IDs to UUIDs

v2 uses GUID-based identifiers instead of integer IDs:

ID Format Changes:

• Space Identifiers - v1 spaceId (integer) becomes spaceUuid (GUID) in v2
• Building Identifiers - v1 buildingId (integer) becomes buildingUuid (GUID) in v2
• Floor Identifiers - v1 floorId (integer) becomes floorUuid (GUID) in v2
• Mapping Support - New mapping files available on request, or use GET /spaces to retrieve current UUIDs

ID Mapping Options:

// Option 1: Use the /spaces endpoint to get current mappings
const spacesResponse = await fetch(`${baseURL}/spaces`, {
  headers: headers,
});
const { spaces } = await spacesResponse.json();

// Find your space by name or other identifier
const mySpace = spaces.find((space) => space.spaceName === "Apartment 1A");
const spaceUuid = mySpace.spaceUuid;
const buildingUuid = mySpace.buildingUuid;
const floorUuid = mySpace.floorUuid;

Migration Mapping File:

If you prefer, request a mapping file from your technical contact containing:

• spaceId → spaceUuid mappings
• floorId → floorUuid mappings
• buildingId → buildingUuid mappings
• siteId → siteUuid mappings

Step 4: Migrate Space Functionality

v1 Implementation:

// v1 approach
const spaceDetails = await fetch(`${v1BaseURL}/spaces/details/${spaceId}`);

v2 Implementation:

// Use spaceUuid for detailed overview
const spaceOverview = await fetch(`${baseURL}/spaces/${spaceUuid}/overview`, {
  headers: headers,
});

// Get aggregated daily electricity data
const metrics = await fetch(
  `${baseURL}/spaces/${spaceUuid}/aggregate/electricity/daily?startDate=2025-01-01&endDate=2025-01-31`,
  {
    headers: headers,
  },
);

// Get aggregated daily temperature data
const temperature = await fetch(
  `${baseURL}/spaces/${spaceUuid}/aggregate/temperature/daily?startDate=2025-01-01&endDate=2025-01-31`,
  {
    headers: headers,
  },
);

// Get aggregated monthly electricity data
const monthlyData = await fetch(
  `${baseURL}/spaces/${spaceUuid}/aggregate/electricity/monthly?startDate=2025-01-01&endDate=2025-12-31`,
  {
    headers: headers,
  },
);

Step 5: Handle Cluster Relationships

v2 provides explicit cluster apartment relationships through the space overview:

// Get space overview which includes cluster information
const spaceOverview = await fetch(`${baseURL}/spaces/${spaceUuid}/overview`, {
  headers: headers,
});

const spaceData = await spaceOverview.json();

// Check if space is part of a cluster
if (spaceData.clusterUuid) {
  // This space belongs to a cluster
  console.log(`Space belongs to cluster: ${spaceData.clusterName}`);

  // Cluster consumption data is available
  const clusterConsumption = spaceData.clusterConsumption;
  // Individual space consumption will be null for cluster spaces
} else {
  // Individual space with its own consumption data
  const individualConsumption = spaceData.consumption;
}

Go-Live Process

Following the onboarding process, v2 migration requires additional verification steps:

Pre-Production Checklist

1. Sandbox Testing

   • Deploy stable version against v2 sandbox for minimum 48 hours
   • Monitor performance and API usage patterns
   • Complete functionality testing across all migrated endpoints

2. Performance Review

   • Schedule go-live meeting with Utopi technical team
   • Review integration performance and API usage
   • Address any technical issues or optimisations
   • Confirm readiness for production migration

3. Production Migration

   • Receive production SiteId values after successful sandbox review
   • Implement production configuration using existing credentials
   • Begin gradual rollout with monitoring