Skip to content

Onboard the remaining Equinix API specs to the SDK #70

Open

Description

@displague

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

  1. script/onboard_service.sh <service> https://docs.equinix.com/api-catalog/<slug>/openapi.yaml (from chore: scaffold for onboarding additional services #60)
  2. Review the generated client; patch the spec rather than the generated code if needed
  3. Add examples/<service> covering basic reads, error handling, and pagination where an operation pages (see examples/README.md)
  4. Open a draft PR; mark write operations in examples with the EQUINIX_EXAMPLE_ALLOW_WRITES guard

Already onboarded

  • fabricv4

In progress (draft PRs, stacked on #60)

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, void order 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

Activity

  1. displague commented on Oct 21, 2026

    @displague
    MemberAuthor

    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 Authorization is a required parameter on every call and every example passes "Bearer " + token by hand. Fabric and crossconnectsv2 instead do client.setBearerToken(token) once. Patching a BearerAuth scheme plus a global security requirement 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

    • Each service generates its own ApiClient, Configuration and ApiException, 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 aggregate equinix-sdk-java artifact.
    • The generated HttpBearerAuth already accepts a Supplier<String> (Java's "call this to get a value" interface) via setBearerToken(Supplier). A supplier backed by accesstokenv1 that 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 one OkHttpClient, 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 a for (Item i : ...) loop) or a Stream<T> (works with .filter().map()) would replace them, and callers wouldn't need to know how each API pages. Specs differ in what offset means (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 emit listAll(...) methods for operations marked with a vendor extension, but the helper alone is most of the value.

    4. Typed errors from ApiException
    ApiException (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 small ApiException template addition such as getErrorAs(Class<T>) (returns Optional<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 (errors typed 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 useSingleRequestParameter option that turns api.searchAssets(auth, ifMatch, offset, limit, sorts, ...) into api.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 with config-help -g java before 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 void because the 201 has no schema, so the order number is lost; attachments' download returns void, so the example drops to the lower-level call. A response schema (type: file for 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions