Repository navigation
Open
Description
Why
Several Equinix APIs are only reachable through older, hand-written standalone sample clients. This SDK is generated from each service's published OpenAPI document, so onboarding the rest of the API catalog gives every service one maintained client and lets the older samples be archived. Generated clients follow their specifications and are not expected to match any earlier sample one-for-one.
Source of truth: https://docs.equinix.com/.well-known/api-catalog
How to onboard a service
script/onboard_service.sh <service> https://docs.equinix.com/api-catalog/<slug>/openapi.yaml(from chore: scaffold for onboarding additional services #60)- Review the generated client; patch the spec rather than the generated code if needed
- Add
examples/<service>covering basic reads, error handling, and pagination where an operation pages (seeexamples/README.md) - Open a draft PR; mark write operations in examples with the
EQUINIX_EXAMPLE_ALLOW_WRITESguard
Already onboarded
- fabricv4
In progress (draft PRs, stacked on #60)
- chore: scaffold for onboarding additional services #60 shared scaffolding (onboarding script,
examples/reactor) - feat: onboard the accesstokenv1 API #61 accesstokenv1
- feat: onboard the troubleticketv1 API #62 troubleticketv1
- feat: onboard the workvisitv1 API #63 workvisitv1
- feat: onboard the assetsv1 API #64 assetsv1
- feat: onboard the smarthandsv1 API #65 smarthandsv1
- feat: onboard the crossconnectsv2 API #66 crossconnectsv2
- feat: onboard the shipmentsv1 API #67 shipmentsv1
- feat: onboard the networkedgev1 API #68 networkedgev1
- feat: onboard the attachmentsv1 API #69 attachmentsv1
- feat(lookupv2): onboard Lookup v2 service with examples #72 lookupv2
- feat: onboard orderhistoryv1 service with examples #73 orderhistoryv1
- feat(ordersv2): onboard the Orders service #74 ordersv2
- feat: onboard the internetaccessv2 API #75 internetaccessv2
- feat: onboard the securecabinetv1 API #77 securecabinetv1
Remaining
Notes: "no scheme" means the spec declares no security scheme, so the Authorization header is a plain per-call parameter (see the UX comment below). OpenAPI 3.1 specs may need generator-support checks.
- accessv1: Access Service (OpenAPI 3.1, 26 paths, paged)
- basv2: Platform Billing Account APIs (3.0, 3 paths)
- billingv1: Billing API (Swagger 2.0, 3 paths, paged, no scheme)
- billingv2: Billing APIs (3.0, 2 paths, paged)
- diloav1: Digital LOA API (3.0, 10 paths)
- getprojectsv2: Project APIs (3.0, 1 path, paged)
- internetaccessv1: Equinix Internet Access API 1.x (3.0, 27 paths, paged)
- notificationsv1: Notification API (Swagger 2.0, 4 paths, paged, no scheme)
- quotesv2: Quote APIs (3.0, 1 path)
- reportsv1: Reports Service API (Swagger 2.0, 9 paths, paged, no scheme)
- shipmentsv2: Shipments (3.0, 2 paths); v2 of feat: onboard the shipmentsv1 API #67
- smartviewv2: Equinix SmartView APIs (3.0, 25 paths, paged)
- stsv1: Security Token Service (OpenAPI 3.1, 8 paths)
- supportplansv2: Smarthands Support Plans (3.0, 1 path, paged, beta)
- supportv2: Case Management API (3.0, 7 paths)
- ticketsv2: Tickets (3.0, 4 paths, beta)
- unifiednotificationv2: Notifications API (3.0, 1 path, paged)
- workvisitsv2: Scheduling Work Visits (3.0, 2 paths); v2 of feat: onboard the workvisitv1 API #63
Not applicable to this generator
- emgv1 (Equinix Messaging Gateway) is published as AsyncAPI, not OpenAPI, so it can't go through this pipeline
Notes
- Spec-level findings from the first batch (untyped error arrays,
voidorder responses, binary downloads, missing security schemes) are in the PRs above; a spec patch is the repo mechanism for fixing them - Where a v1 and v2 of the same service both exist, v1 is onboarded first only because it matches existing sample usage; either order is fine
Metadata
Metadata
Assignees
Labels
No labels
Activity
displague commentedon Oct 21, 2026
Possible SDK-wide UX improvements that came up while writing the examples in #61–#69. Each is small and fits the existing generator + template + patch setup; none needs to block onboarding. Ordered roughly by payoff.
1. Make auth look the same in every service (spec patch)
The Swagger 2.0 specs (assets, attachments, shipments v1, smarthands, troubleticket, workvisit) declare no security scheme, so
Authorizationis a required parameter on every call and every example passes"Bearer " + tokenby hand. Fabric and crossconnectsv2 instead doclient.setBearerToken(token)once. Patching aBearerAuthscheme plus a globalsecurityrequirement into those specs would give every service the same setup and drop the extra argument from every method signature.2. A shared way to build clients and keep tokens fresh
ApiClient,ConfigurationandApiException, so there's no single place to set base URL, timeouts or credentials.ExampleEnv(from chore: scaffold for onboarding additional services #60) already does this for the examples; a small version of it could ship in the aggregateequinix-sdk-javaartifact.HttpBearerAuthalready accepts aSupplier<String>(Java's "call this to get a value" interface) viasetBearerToken(Supplier). A supplier backed byaccesstokenv1that caches the token and re-requests it shortly before expiry would let long-running programs avoid expired tokens without any generator change.ApiClient.setHttpClient(...)lets several services share oneOkHttpClient, which shares connection pools and timeouts.3. A pagination helper (Java idiom:
Iterable/Stream)Five of the new examples hand-write the same offset/limit loop with a page cap. A tiny shared class that takes "fetch the page at this offset" and returns an
Iterable<T>(works in afor (Item i : ...)loop) or aStream<T>(works with.filter().map()) would replace them, and callers wouldn't need to know how each API pages. Specs differ in whatoffsetmeans (item offset vs page number, as noted in #69), so the helper should take the paging rule as a parameter. Longer term a template tweak could emitlistAll(...)methods for operations marked with a vendor extension, but the helper alone is most of the value.4. Typed errors from
ApiExceptionApiException(the exception every call throws, a "checked" exception, meaning callers must catch or declare it) only exposes status code, headers and the raw body, so every example re-parses the body with a fallback. The repo already overrides templates for fabricv4; a smallApiExceptiontemplate addition such asgetErrorAs(Class<T>)(returnsOptional<T>, empty if the body doesn't parse) would give one idiomatic way to read errors. It works best together with spec patches for error schemas that don't match real bodies (errorstyped as strings in troubleticket/smarthands, array-of-error with no wrapper in shipments).5. Request objects instead of long parameter lists (generator option)
The java generator has a
useSingleRequestParameteroption that turnsapi.searchAssets(auth, ifMatch, offset, limit, sorts, ...)intoapi.searchAssets(request)with a builder-style request object. It is a breaking change for existing callers, so I'd turn it on for new services only (or for fabricv4 at the next major). Worth confirming the option name against 7.16.0 withconfig-help -g javabefore relying on it.6. Naming clean-up (generator mappings or spec patches)
Some generated names are awkward and will stick once published:
Genricerrorinfo(typo in the spec),DurationVisitEnum._2_HOURS,Oauth2TokenRequest. The generator can rename models and enums via per-service mappings (modelNameMappings,enumNameMappings), or the typo can be fixed in a spec patch. Cheap now, a breaking change later.7. Fill in missing response types (spec patch)
Smarthands orders generate as
voidbecause the 201 has no schema, so the order number is lost; attachments' download returnsvoid, so the example drops to the lower-level call. A response schema (type: filefor the download) in a patch makes these methods return something usable.Suggested order: 1 and 7 as part of onboarding each v1 service, 3 and 4 as one small follow-up PR, 2 and 5/6 when the first batch has merged.