Service Backend Dependency Analysis

Overview

The Service Dependency Repository is a component that analyzes service configurations to identify shared backend infrastructure. It helps API publishers understand the potential "blast radius" of a backend infrastructure failure by reporting which services depend on the same servers, web servers, or exact endpoint URLs.

This component operates by reading service configuration data from the platform's database. It does not modify any data. Its primary functions are to:

1. Find all groups of services that share a common backend dependency.
2. For a given service, find all other services that are related to it through a shared backend.

The analysis is performed at three distinct levels of dependency:

• Same Server (HOST): Services whose backend endpoint URLs resolve to the same hostname.
• Same Web Server (HOST_PORT): Services whose backend endpoint URLs resolve to the same hostname and port combination.
• Same Endpoint (ENDPOINT): Services that use the exact same backend endpoint URL string.

How it Works

The dependency analysis process involves data retrieval, URL parsing, and grouping based on the level of dependency.

flowchart TD
    subgraph Dependency Analysis Process
        A[API Call: findSharedGroups() or findRelatedServices()] --> B{Load Service Backends};
        B --> C[Database];
        C -- Raw service data -- > B;
        B -- Service list -- > D{For each service};
        D --> E[Parse Backend Endpoint URL];
        E -- Parsed host, port, host:port -- > D;
        D -- Parsed service list --> F{Group Services};
        F -- "By HOST, HOST_PORT, or ENDPOINT" --> G[Generate Report];
        G -- Dependency report --> H[Return Results];
    end

    subgraph "URL Parsing (Step E)"
        direction LR
        U_IN[Endpoint URL String] --> P1{Parse with URI};
        P1 -- "host, port, scheme" --> P2{Normalize Host};
        P2 --> P3{Infer Default Port};
        P3 -- "e.g., http -> 80, https -> 443" --> P_OUT[Parsed Host, Port, Host:Port];
        P1 -- on URISyntaxException --> P_ERR{Fallback: Use raw string as host};
        P_ERR --> P_OUT;
    end

1. Data Retrieval: The process begins by executing a SQL query against the platform database to retrieve a list of all active services and their default backend endpoint URLs. The query joins the s2r_service and s2r_backend_profile tables. It explicitly filters out services with a deprecated status or those with a null or empty endpoint_url.

   IMPORTANT

   The data retrieval is scoped to the services belonging to a single tenant. This ensures that dependency analysis for one API publisher does not include or leak information about services belonging to another.

2. Endpoint URL Parsing: For each service retrieved, its backend endpoint_url is parsed to extract its constituent parts:

   • The system uses Java's URI class for parsing.
   • The hostname is extracted and normalized to lowercase. It can handle hostnames present in the authority part of a URL (e.g., after an @ symbol).
   • The port is identified. If a port is not explicitly present in the URL, a default is inferred based on the scheme: http defaults to port 80, and https defaults to port 443. No default port is inferred for other schemes.
   • A combined hostPort string (e.g., api.example.com:443) is constructed.
   • If a URL has invalid syntax, the entire raw string is used as the hostname as a fallback.

3. Grouping and Analysis: The parsed service data is then analyzed based on the method called:

   • findSharedGroups(): Services are grouped by hostname, hostPort, and endpointUrl. Any group containing more than one service is considered a "shared group" and is included in the results.
   • findRelatedServices(serviceId): The system first identifies the "anchor" service specified by serviceId. It then finds all other services that share the same hostname, hostPort, or endpointUrl as the anchor. The results are sorted to show the most closely related services first (Same Endpoint, then Same Web Server, then Same Server).

API Reference

The repository exposes two methods for dependency analysis.

findSharedGroups()

Finds all groups of two or more services that share backend infrastructure. The results are sorted by dependency level, then by the number of services in the group (descending), and finally by the shared target identifier.

• Parameters: None.
• Returns: A List of Map<String, Object>, where each map represents a group of services sharing a dependency.

Shared Group Fields

Each object in the returned list has the following structure:

findRelatedServices(UUID serviceId)

Finds all services that share backend infrastructure with a specific "anchor" service.

• Parameters:
  • serviceId (UUID): The unique identifier of the service to use as the anchor for the analysis.
• Returns: A Map<String, Object> containing the analysis results. If the serviceId is not found, the relatedServices and dependencySummary lists will be empty.

findRelatedServices Response Structure

The returned map contains the following top-level keys:

Anchor Fields

Dependency Summary Fields

Each object in the dependencySummary list has the following structure:

Related Service Fields

Each object in the relatedServices list has the following structure. The list is sorted by dependency rank (endpoint, then host/port, then host), then by environment, then by service key.

Data Source

The component retrieves service data using the following SQL query. This is provided for visibility into the exact data source.

select s.id as service_id,
       s.environment,
       s.service_key,
       s.service_name,
       s.status,
       s.debug_enabled,
       bp.endpoint_url
from s2r_service s
join s2r_backend_profile bp on bp.id = s.default_backend_profile_id and bp.tenant_id = s.tenant_id
where s.status <> 'deprecated'
  and bp.endpoint_url is not null
  and trim(bp.endpoint_url) <> ''
  and s.TENANT_ID = ? -- TENANT_SCOPE_SQL is replaced with a tenant predicate
order by s.environment, s.service_key

Troubleshooting

• Incorrect Grouping for Malformed URLs: If a service's backend endpoint URL has invalid syntax (e.g., http://[invalid-host), the parser will fall back to using the entire raw string as the hostname. This may cause the service to be excluded from its correct dependency group or be grouped incorrectly.
• Service Not Found: When calling findRelatedServices, if the provided serviceId does not match an active service with a configured backend URL, the method will return a result with empty relatedServices and dependencySummary lists.
• Non-Standard Ports: The system only infers default ports for http (80) and https (443) schemes. If services use a backend on a non-standard port without specifying it in the URL (e.g., http://api.example.com for a service running on port 8080), they will not be correctly grouped at the HOST_PORT level.

All SOAP-to-REST docs