Contributing

Development setup, resource pattern, testing standards and change submission.

Setup#

Requirement	Version
JDK	21
Maven	3.6 or later
Equinix API credentials	Only for the live test tiers

Shell

git clone https://github.com/iantjones/equinix-java-sdk.git
cd equinix-java-sdk
mvn clean compile
mvn test
mvn test -Pwiremock
mvn -Pcoverage verify
mvn javadoc:javadoc

The last command fails the build on a broken {@link} or @see reference. Javadoc runs on the sources before Lombok generates code, so a reference to a Lombok-generated getter has to be written as {@code getX()}, because {@link #getX()} does not resolve.

Resource pattern#

Each API resource follows one of two layouts.

Call path for one resource. A mutable resource adds a wrapper that carries update, delete and refresh, and an operator that holds the fluent builders.

Layer	Mutable resource	Read-only resource
Model interface	Public getters	Public getters
JSON model	Jackson-annotated class implementing the interface	Implements the interface directly
Wrapper	Adds `update()`, `delete()`, `refresh()`	None
Public client interface and implementation	`list`, `search`, `getByUuid`, `define`	`list`, `getByUuid`
Internal client interface and implementation	Builds and executes the HTTP requests	Same
Operator	Fluent builders for create and update	None

Endpoints are declared in src/main/resources/json/apiParams_*.json, one file per functional area. The design engines depend on the FabricGateway interface, so they can be unit-tested against a stub gateway without a Fabric client.

Conventions#

Method names: list, search, getByUuid or getBy<Key>, define or create, update, delete. Javadoc cites the specification's operationId.
Every Jackson field has an explicit @JsonProperty.
Enums implement APIParam. Read-side enums return UNKNOWN for a value they do not list. The query form of an enum equals its body form, and ApiParamContractTest enforces that.
Request-side builders take enums where the specification defines an enumeration.
Do not add a field or an operation that the specification and the live service both lack. Several such surfaces were removed in 3.0.0 and 4.0.
Every source file carries the Apache 2.0 license header.

Testing standards#

Requirements for new code:

Negative-path tests for every cache and every external call. A cache needs a test in which the first lookup fails with a transient error and a later lookup retries. An external HTTP call needs a timeout test.
Parity tests where two code paths must produce the same artifact. Extract one builder and prove that both paths emit the same bytes. The wizard's router dry run and router create share one body builder for this reason.
Doc-contract tests. A behaviour that Javadoc promises has a test that enforces it and quotes the Javadoc line. Change the two together.
Corpus stubs for errors observed live. Every real error from the live API gets a regression test stubbed with the JSON body the API returned, unedited.
Stubs that encode observed behaviour. A WireMock stub should reproduce a response captured from the live API or taken from the specification. When a live run contradicts a stub, correct the stub first and the code second.
Assertions that would fail on a defect. Coverage shows that code ran and does not show that its result was checked, so a surviving PIT mutant in changed code indicates a missing assertion.

Rule 5 was added after the review of 2026-11-11 found tests whose fixtures had been written to match the SDK, and which therefore passed with a wrong host, a wrong content type or a wrong field name.

Submitting#

Open an issue first for anything larger than a fix, using the bug report or feature request template. State the SDK version, the Java version and the affected domain, and cite the Equinix API operation.
Fork, and branch from main.
Add tests that meet the standards above.
Run mvn test, mvn test -Pwiremock and mvn javadoc:javadoc.
Open a pull request that says what changed and how it was verified.

Contributions are licensed under the Apache License 2.0.

Security reports#

Do not open a public issue for a vulnerability. Contact the maintainer privately through the GitHub repository owner profile, and include the SDK version and a minimal reproduction.