Upgrade notes for 4.0 New in 4.0

Every breaking change between 3.0.0 and the 4.0 tree, with the replacement, and the fixes that change behaviour without changing a signature.

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#

The following fixes change behaviour and leave the method signatures as they were. Code that worked around one of these defects no longer needs the workaround.

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.