API Regional Deployment Guide

This documentation guides API Providers through the Console deployment process, mapped to their specific backend hosting architecture. The Console UI now automatically determines the optimal Gateway by referencing the physical deployment location of the API providers’ target endpoints.

1. Overview

In the new deployment model, API publishers first select their Deployment Type (Global or Regional).

Global Deployments: Route traffic dynamically across Azure’s worldwide network of data centers via a single global consumption endpoint.
Regional Deployments: API publishers select their target region and provide backend details. Map the API to a specific regional gateway based on the selected cloud provider and geographic region.

Deployment Prerequisites

To deploy an API, API Provider should provide the below details:

Deployment Type: Global or Regional
Target Gateway (If Deployment type is Regional only): The cloud provider hosting your API (Azure or AWS)
Target Region (If Deployment type is Regional only): The specific geographic location of your backend
Backend URL & Timeout: The source endpoint and its response threshold

2. Supported Deployment Architecture

Global Deployment

Deploying a target endpoint as ‘Global’ leverages Azure’s worldwide network of data centers. It bypasses provider specific region selections.

Regional Deployment

If Regional is selected, available regions are categorized by the cloud provider hosting the backend:

Azure

Americas: East US, East US 2, South Central US, West US, West US 2, West US 3, West Central US
Europe: North Europe
Asia Pacific: Australia East, Australia Southeast, Central India

AWS

North America: US East (N. Virginia), US East (Ohio), US West (N. California), US West (Oregon), Central US
Europe: Europe (Stockholm)
Asia Pacific: Singapore, Sydney, Jakarta, Melbourne, Malaysia, New Zealand

3. Regional Groups and Validation

Validation Logic

To prevent configuration conflicts, multi-region deployments within the same Regional Group are restricted.

Example: If an API is already deployed in an Azure region in Australia, a second deployment to an AWS region in Australia is prohibited because they share the same regional group and consumption domain.

Regional Mapping Table

Regional Group	Provider Regions	Stage Consumption Domain	Prod Consumption Domain
Global	Azure: Global Network	`https://cloud.stage.api.trimblecloud.com`	`https://cloud.api.trimble.com`
US East	Azure: East US, East US 2, South Central US AWS: N. Virginia, Ohio	`https://us-east.stage.api.trimblecloud.com`	`https://us-east.api.trimble.com`
US West	Azure: West US, West US 2, West US 3, West Central US AWS: N. California, Oregon, Central US	`https://us-west.stage.api.trimblecloud.com`	`https://us-west.api.trimble.com`
Europe	Azure: North Europe AWS: Stockholm	`https://eu.stage.api.trimblecloud.com`	`https://eu.api.trimble.com`
Australia	Azure: Australia East, SE AWS: Sydney, Melbourne	`https://ap-au.stage.api.trimblecloud.com`	`https://ap-au.api.trimble.com`
Singapore	AWS: Singapore, Jakarta	`https://ap-sg.stage.api.trimblecloud.com`	`https://ap-sg.api.trimble.com`
Central India	Azure: Central India	`https://ap-in.stage.api.trimblecloud.com`	`https://ap-in.api.trimble.com`
Malaysia	AWS: Malaysia	`https://ap-my.stage.api.trimblecloud.com`	`https://ap-my.api.trimble.com`
New Zealand	AWS: New Zealand	`https://ap-nz.stage.api.trimblecloud.com`	`https://ap-nz.api.trimble.com`

4. Legacy Support

Existing APIs using legacy endpoints will continue to be supported seamlessly. However, all new deployments must follow the new deployment patterns defined above.

Legacy Endpoints:

Dev: https://cloud.dev.api.trimblecloud.com/
QA: https://cloud.qa.api.trimblecloud.com/
Stage: https://cloud.stage.api.trimblecloud.com/
Prod: https://cloud.api.trimble.com/

5. Step-by-Step Deployment Process

Start: Click the Add new deployment button under the API Configuration tab.
Configuration: Enter your Backend URL and Timeout value.
Select Deployment Type: Choose between Global or Regional.
- If Global is selected: The UI will skip provider selection and automatically display the generated Global consumption endpoint. Proceed directly to Step 6.
- If Regional is selected: Proceed to Step 4.
Target Selection: Under “Where is the target API deployed?”, select Azure or AWS.
Region Selection: Choose the appropriate region from the populated list.
Review: The UI will display the selected gateway region and the generated consumption endpoint.
Finalize: Click Add deployment to initiate the process.