Upgrade notes for 4.0 New in 4.0

Breaking changes between 3.0.0 and the 4.0 tree with their replacements, and behaviour fixes.

Status#

4.0.0 is in development. This page reflects the working tree on 2026-11-12 and will gain entries until the release. The authoritative list is the [Unreleased] section of CHANGELOG.md.

Release 3.0.0 renamed every package from api.equinix.javasdk to com.eqixiac.equinix and changed the Maven coordinates to com.eqixiac.equinix:equinix-sdk-java. A project on 2.x applies that rename before the changes on this page.

Breaking changes#

Fabric#

3.0.0	4.0	Reason
`AwsDirectConnectAdapter.of(account, region, profile)` and the other three-argument adapter factories	A metro code is the last argument: `of(account, region, profile, "DC")`	Fabric rejects a service-provider Z-side without `location.metroCode` (HTTP 400 `EQ-3142501`)
`AzureExpressRouteAdapter.of(key, region, profile, peeringType)`	`of(key, profile, peeringType, metro)`	The service key fixes the region
`zSideAccessPointServiceProfile(uuid, linkProtocol)`	`zSideAccessPointServiceProfile(uuid, linkProtocol, metroCode)`	Same
`connections().getStatistics(...)`, `ports().getStatistics(...)`, `ConnectionStatistic`, `PortStatistic`	`fabric.metrics().forConnection(...)`, `forPort(...)`	The statistics models had no operation behind them that matched the specification
`ports().list()` returns `PaginatedList<Port>`	Returns `List<Port>`; `search(...)` pages	Follows the endpoint
`PrecisionTimes.list()` calls `GET /timeServices`	Calls `POST /timeServices/search`	No `GET /timeServices` in the specification; 502 live
`AccessPointType.XF_IC`	`AccessPointType.IC`	Specification 4.34.0
`fabric.client.RequestBuilder`, `NatType`, `PortSettings` and related models	Removed	Unused or absent from the specification

Customer Portal#

3.0.0	4.0
`WorkVisitLocation` and its account, cage and cabinet models	`workVisits().listLocations()` returns `LookupLocation`
`CasePriority`, `CaseStatus`, `MediaType` enums	Removed; absent from the specifications

Core#

3.0.0	4.0
Only client-credentials constructors	`BearerTokenProvider` constructors added on `Equinix` and every domain client. Additive.
No replay after 401	One replay after a 401 with a new token. Behaviour change: a call that used to fail with `EquinixAuthenticationException` after token revocation can now succeed.
`loadAll()` trusts `total`	Stops on an empty or repeated page

Design layer#

The Metro Optimizer was rebuilt around the DesignSpec document and a portfolio solver. The fluent builder remains, with the following changes to its methods.

3.0.0	4.0
`.scoringWeights(ScoringWeights.builder()...)`	`.weights(Map<String, Double>)` keyed by objective id, or a named profile through `.strategy(...)`
`.constraints().monthlyBudget(min, max)`	`.monthlyBudget(max)` or `.monthlyBudget(BigDecimal max, String currency)`
`.addWorkload(...).profile(WorkloadProfile...)`, `.requiresHighPowerDensity()`	Removed from the builder; see Metro Optimizer for the current workload inputs
Metros scored one at a time	Portfolios of metros scored as a set; the result adds `getRecommended()`, `getFrontier()`, `getSensitivity()` and `getPlacement()`
Latency fallback one-way, unknown latency assumed 150 ms	All latencies round-trip; an unknown latency stays unknown and is excluded from scoring

MCP server#

3.0.0	4.0
`fabric_confirm_change` executes when the client has no elicitation support	Executes nothing, unless `EQUINIX_MCP_ALLOW_UNCONFIRMED_MUTATIONS=true`
Confirmation prompt shows a summary	Shows every field the create will send
Mistyped spec values are dropped	Mistyped spec values are rejected

Fixes from live validation#

These fixes change behaviour without changing a signature. Remove any workaround for the old behaviour.

Area	3.0.0 behaviour	4.0 behaviour
IAM and STS host	Requests to `api.equinix.com`, answered 404	`access.eqix.equinix.com` and `sts.eqix.equinix.com`
STS token exchange	camelCase form fields, rejected by the service	RFC 8693 field names; snake_case responses read
STS public operations	Triggered an Equinix login	Sent without credentials
Customer Portal paging	Attachments, finance accounts, reports and asset search stopped after page one	`page` envelope read
Timestamps	Only 1, 2, 3 or 6 fractional digits accepted; a 9-digit value failed the whole response	0 to 9 digits and `Z`, `+HH`, `+HHMM`, `+HH:MM` offsets
Unknown response fields	Failed the read on models without an ignore annotation	Ignored on every model
Service-profile replace	No `If-Match` header	Sends the `ETag` of the preceding read
Stream alert-rule update	`PATCH`	`PUT`
`ServiceToken.getChangeLog()`	Always null	Populated
Network Edge license upload	JSON body	`multipart/form-data`
Order history	Account and contact fields null	Live field names read
Metrics calls	Sent a `limit` the service rejects	No `limit`
Live rate card	Every lookup failed with 400 and fell back to reference prices silently	Targeted queries; live prices used
Peering Intelligence	No presence found for any network	Queries PeeringDB by network id; resolves facilities through live metro codes
Savings calculator	Omitted the cloud provider's port fee	Nets it out; AWS 1 Gbps in DC is USD 3081 per month net, not 3300
MCP `portal_list_open_tickets`	Always failed with 400	Works; reports truncation
Debug logging	Could write `client_secret` and tokens	Masked
Live test credentials	`-D` system properties, copied into Surefire reports	Environment variables

Additions#

fabric.beta(): the Fabric v4 Beta families
BearerTokenProvider and 401 recovery
DesignSpec, the portfolio solver, sensitivity analysis and workload placement
Native cloud-to-cloud links in the TCO and savings calculators, the Deployment Wizard and two MCP tools (Beta)
ActivationKey decoding and the Fabric provider-environment operations (Beta)
HealthStatus.getAllApiServices(), DeviceCore.getTiers(), Metric.getSummaryNode()
AccessPointBuilder.metro(...), CloudProviderConnectionAdapter.getMetroCode()
StsScope, ProjectIds, MetricQuery, CloudEventQuery

Procedure#

Update the dependency version and compile. The compiler reports every removed type and changed signature.
Add the metro code to each cloud adapter and service-profile Z-side.
Replace statistics calls with metrics calls.
Remove workarounds for the defects in the table above, such as a manual host override for IAM.
Run your own dry-run suite against the sandbox or with the dryRun() builders before the first real create.