Class PeeringDbClient

java.lang.Object
com.eqixiac.equinix.design.peering.client.PeeringDbClient
All Implemented Interfaces:
AutoCloseable
public class PeeringDbClient extends Object implements AutoCloseable
Lightweight HTTP client for the PeeringDB REST API.

Provides access to PeeringDB's network, internet exchange, facility, and organization data with optional API key authentication. Uses Apache HttpClient (the same transport library as the Equinix SDK core) for HTTP communication and Jackson for JSON deserialization.

Equinix-Scoped Data

This client includes built-in support for loading the Equinix organization (org_id=2) with all nested IXes and facilities in a single call via loadEquinixCatalog(). Subsequent per-ASN queries can then be filtered against the cached Equinix IX and facility IDs.

Authentication

PeeringDB allows unauthenticated read access with rate limiting (~20 requests/minute). Providing an API key via the constructor increases rate limits and grants access to contact information fields.

Rate limiting

An HTTP 429 from PeeringDB is retried up to 3 times, honouring the Retry-After response header (seconds or HTTP-date form) and falling back to a small exponential backoff when the header is absent or unparsable. The total time spent waiting for a single logical request is capped at 30000L ms - a Retry-After beyond the remaining budget fails fast instead of stalling the caller. Multi-ASN lookups should prefer the batched collection overloads (getNetworks, getEquinixIxPresence(Collection), getEquinixFacPresence(Collection)), which use PeeringDB's asn__in query operator to collapse N per-ASN requests into one request per endpoint - the single most effective way to stay under the anonymous limit.

Lifecycle

The client owns a CloseableHttpClient and is itself AutoCloseable: whoever constructs a PeeringDbClient owns closing it (the analysis engine never closes a client it was handed). PeeringIntelligence.Builder.analyze() constructs its own client and closes it when the analysis completes.

Usage

try (PeeringDbClient client = new PeeringDbClient("your-api-key")) {
    client.loadEquinixCatalog();

    PeeringDbNetwork aws = client.getNetwork(16509);
    List<PeeringDbNetIxlan> awsIxPresence = client.getEquinixIxPresence(16509);
    List<PeeringDbNetFac> awsFacPresence = client.getEquinixFacPresence(16509);
}
Author:
ianjones
See Also:

  • Constructor Details

    • PeeringDbClient

      public PeeringDbClient(String apiKey)
      Creates a PeeringDB client with API key authentication for higher rate limits.
      Parameters:
      apiKey - the PeeringDB API key, or null for unauthenticated access

    • PeeringDbClient

      public PeeringDbClient()
      Creates a PeeringDB client with unauthenticated access (~20 requests/minute).

  • Method Details

    • withBaseUrl

      public static PeeringDbClient withBaseUrl(String apiKey, String baseUrl)
      Creates a PeeringDB client pointed at an alternate API base URL.

      Test seam. This exists so the HTTP/parsing paths can be exercised against a local stub server; production code should use the no-arg or API-key constructors, which target the real PeeringDB endpoint.

      Parameters:
      apiKey - the PeeringDB API key, or null for unauthenticated access
      baseUrl - the API base URL (e.g. http://localhost:PORT/api)
      Returns:
      a client that issues requests against baseUrl

    • loadEquinixCatalog

      public void loadEquinixCatalog() throws IOException
      Loads the complete Equinix organization catalog from PeeringDB, including all internet exchanges (ix_set) and facilities (fac_set).

      This makes a single API call to /api/org/2?depth=2 and caches the results. All subsequent calls to getEquinixIxPresence(long) and getEquinixFacPresence(long) filter against this cached catalog.

      Throws:
      IOException - if the API call fails

    • getNetwork

      public PeeringDbNetwork getNetwork(long asn) throws IOException
      Retrieves network metadata for a given ASN.
      Parameters:
      asn - the autonomous system number
      Returns:
      the network metadata, or null if not found
      Throws:
      IOException - if the API call fails

    • getNetIxlans

      public List<PeeringDbNetIxlan> getNetIxlans(long asn) throws IOException
      Retrieves all IX LAN presence records for a given ASN.
      Parameters:
      asn - the autonomous system number
      Returns:
      all netixlan entries for this ASN across all IXes
      Throws:
      IOException - if the API call fails

    • getNetFacs

      public List<PeeringDbNetFac> getNetFacs(long asn) throws IOException
      Retrieves all facility presence records for a given ASN.
      Parameters:
      asn - the autonomous system number
      Returns:
      all netfac entries for this ASN across all facilities
      Throws:
      IOException - if the API call fails

    • getNetworks

      public Map<Long, PeeringDbNetwork> getNetworks(Collection<Long> asns) throws IOException
      Retrieves network metadata for multiple ASNs in batched net?asn__in=... requests - one HTTP request per 150 ASNs instead of one per ASN.

      A single-element collection delegates to getNetwork(long) (the plain asn= query), so subclass stubs and per-ASN behaviour stay identical for that case.

      Parameters:
      asns - the autonomous system numbers (duplicates are collapsed)
      Returns:
      map of ASN to network metadata; ASNs PeeringDB does not know are absent from the map
      Throws:
      IOException - if any API call fails

    • getNetIxlans

      public Map<Long, List<PeeringDbNetIxlan>> getNetIxlans(Collection<Long> asns) throws IOException
      Retrieves IX LAN presence records for multiple ASNs in batched netixlan?asn__in=... requests, grouped by ASN.

      A single-element collection delegates to getNetIxlans(long).

      Parameters:
      asns - the autonomous system numbers (duplicates are collapsed)
      Returns:
      map of ASN to its netixlan entries; every requested ASN is present as a key (with an empty list when it has no entries)
      Throws:
      IOException - if any API call fails

    • getNetFacs

      public Map<Long, List<PeeringDbNetFac>> getNetFacs(Collection<Long> asns) throws IOException
      Retrieves facility presence records for multiple ASNs in batched netfac?asn__in=... requests, grouped by ASN (local_asn).

      A single-element collection delegates to getNetFacs(long).

      Parameters:
      asns - the autonomous system numbers (duplicates are collapsed)
      Returns:
      map of ASN to its netfac entries; every requested ASN is present as a key (with an empty list when it has no entries)
      Throws:
      IOException - if any API call fails

    • getEquinixIxPresence

      public List<PeeringDbNetIxlan> getEquinixIxPresence(long asn) throws IOException
      Retrieves IX LAN presence records for a given ASN, filtered to Equinix IXes only.

      Requires loadEquinixCatalog() to have been called first.

      Parameters:
      asn - the autonomous system number
      Returns:
      netixlan entries at Equinix internet exchanges only
      Throws:
      IOException - if the API call fails
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixFacPresence

      public List<PeeringDbNetFac> getEquinixFacPresence(long asn) throws IOException
      Retrieves facility presence records for a given ASN, filtered to Equinix facilities only.

      Requires loadEquinixCatalog() to have been called first.

      Parameters:
      asn - the autonomous system number
      Returns:
      netfac entries at Equinix facilities only
      Throws:
      IOException - if the API call fails
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixIxPresence

      public Map<Long, List<PeeringDbNetIxlan>> getEquinixIxPresence(Collection<Long> asns) throws IOException
      Retrieves IX LAN presence records for multiple ASNs, filtered to Equinix IXes only, using batched asn__in requests (one per 150 ASNs instead of one per ASN).

      A single-element collection delegates to getEquinixIxPresence(long), preserving the plain asn= wire shape (and any subclass behaviour) for that case. Multi-ASN calls require loadEquinixCatalog() to have been called first.

      Parameters:
      asns - the autonomous system numbers (duplicates are collapsed)
      Returns:
      map of ASN to its netixlan entries at Equinix IXes; every requested ASN is present as a key (with an empty list when it has none)
      Throws:
      IOException - if any API call fails
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixFacPresence

      public Map<Long, List<PeeringDbNetFac>> getEquinixFacPresence(Collection<Long> asns) throws IOException
      Retrieves facility presence records for multiple ASNs, filtered to Equinix facilities only, using batched asn__in requests.

      A single-element collection delegates to getEquinixFacPresence(long). Multi-ASN calls require loadEquinixCatalog() to have been called first.

      Parameters:
      asns - the autonomous system numbers (duplicates are collapsed)
      Returns:
      map of ASN to its netfac entries at Equinix facilities; every requested ASN is present as a key (with an empty list when it has none)
      Throws:
      IOException - if any API call fails
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixOrg

      public PeeringDbOrg getEquinixOrg()
      Returns the cached Equinix organization data.
      Returns:
      the Equinix org, or null if not yet loaded

    • getEquinixIxMap

      public Map<Integer, PeeringDbIx> getEquinixIxMap()
      Returns the map of Equinix IX ID to IX metadata.
      Returns:
      unmodifiable map of IX ID to PeeringDbIx
      Throws:
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixFacMap

      public Map<Integer, PeeringDbFacility> getEquinixFacMap()
      Returns the map of Equinix facility ID to facility metadata.
      Returns:
      unmodifiable map of facility ID to PeeringDbFacility
      Throws:
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixIxIds

      public Set<Integer> getEquinixIxIds()
      Returns the set of all Equinix IX IDs for filtering.
      Returns:
      unmodifiable set of PeeringDB IX IDs belonging to Equinix
      Throws:
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixFacIds

      public Set<Integer> getEquinixFacIds()
      Returns the set of all Equinix facility IDs for filtering.
      Returns:
      unmodifiable set of PeeringDB facility IDs belonging to Equinix
      Throws:
      IllegalStateException - if the Equinix catalog has not been loaded

    • getEquinixIx

      public PeeringDbIx getEquinixIx(int ixId)
      Looks up an Equinix IX by its PeeringDB ID.
      Parameters:
      ixId - the PeeringDB IX ID
      Returns:
      the IX metadata, or null if not an Equinix IX

    • getEquinixFacility

      public PeeringDbFacility getEquinixFacility(int facId)
      Looks up an Equinix facility by its PeeringDB ID.
      Parameters:
      facId - the PeeringDB facility ID
      Returns:
      the facility metadata, or null if not an Equinix facility

    • close

      public void close()
      Closes the underlying HTTP client. Quiet by design: a close failure releases nothing actionable to the caller, and the analysis result it would otherwise mask is already in hand. Safe to call more than once. Ownership: whoever constructed this client closes it - the analysis engine never closes a client it was handed.
      Specified by:
      close in interface AutoCloseable