Akana API Platform Discovery Service

Overview

The Akana Discovery Service automates the discovery of APIs and services from a Perforce Akana API Platform instance. It connects to the Akana Platform Management REST API, fetches all consumer-facing APIs and backend business services, and synchronizes them with the platform's service catalog.

This service is designed for API publishers who use Akana as an API gateway and need to maintain an up-to-date inventory of their services within this platform. The service runs as a discovery pass for a specific, pre-configured Akana instance.

Its primary inputs are the credentials for an Akana instance, identified by a gatewayType of akana and a unique instanceName. Its main output is the creation and updating of records in the s2r_discovered_service database table. It also deactivates records for services that are no longer present in the Akana instance.

How it Works

The discovery process executes a series of steps to query the Akana API, process the results, and persist them to the local database.

flowchart TD
    subgraph "Initialization"
        A[Start runDiscovery] --> B{Load Credentials};
        B --> C[Instantiate Akana API Client];
    end

    subgraph "Data Fetching"
        C --> D[GET /api/apis];
        C --> E[GET /api/services];
        D --> F[For each API];
        F --> G[GET /api/apis/:id];
        E --> H[For each Service];
        H --> I[GET /api/services/:id];
    end

    subgraph "Data Processing & Persistence"
        G --> J[Map API to Discovered Entry];
        I --> K[Map Service to Discovered Entry];
        J --> L[Collect All Entries];
        K --> L;
        L --> M[Upsert into s2r_discovered_service];
        M --> N[Mark Stale Services Inactive];
    end

    subgraph "Completion"
        N --> O[Return DiscoveryResult];
        O --> P[End];
    end

Discovery Workflow

The service follows this sequence of operations:

1. Load Credentials: The runDiscovery method is invoked with a gatewayType and instanceName. It retrieves the decrypted credentials (host, port, username, password) for the specified Akana instance from the s2r_lb_connector_credentials table via the LbConnectorCredentialService.
2. Initialize Client: An AkanaPlatformClient is created to communicate with the Akana Platform Management REST API. If a port is not specified in the credentials, it defaults to 9900.
3. Discover APIs: The service sends a request to the Akana /api/apis endpoint to get a list of all consumer-facing APIs. For each API in the list, it sends a follow-up request to /api/apis/{id} to fetch its detailed configuration.
4. Discover Services: The service sends a request to the Akana /api/services endpoint to get a list of all business services (backend mappings). For each service, it sends a follow-up request to /api/services/{id} for its details.
5. Process and Map: For each API and service, the service extracts key information:
   • A unique vendor_service_id is created with the format api:<id> for APIs and service:<id> for services.
   • A displayName is constructed from the service's name and version fields (e.g., PaymentService v2.0).
   • Frontend and backend connection details (host, port, protocol) are parsed from the endpointUrl field.
   • The complete, raw JSON response from Akana is preserved in the raw_metadata field for auditing and troubleshooting.
6. Persist to Database: The collected service entries are upserted into the s2r_discovered_service table.
   • If a service with a matching vendor_service_id already exists, its record is updated with the latest information, and its is_active flag is set to true.
   • If the service is new, a new record is inserted.
7. Deactivate Stale Records: After processing all services from the current discovery run, the service identifies any records in the database for the same Akana instance that were not seen in this run. These stale records are marked as inactive by setting their is_active flag to false.
8. Return Result: The process concludes by returning a DiscoveryResult object containing statistics for the run, including the number of services discovered, added, updated, and marked inactive, along with a list of any errors encountered.

Data Mapping

The service maps data from the Akana API to fields in the s2r_discovered_service table as follows:

API Reference

The service exposes a single public method to initiate a discovery pass.

runDiscovery

Triggers a full discovery pass for a configured Akana instance.

DiscoveryResult runDiscovery(String gatewayType, String instanceName)

Parameters:

Returns:

A DiscoveryResult object containing the outcome of the discovery pass. The structure includes:

Exceptions:

• LbConnectorCredentialService.NotFoundException: Thrown if credentials for the specified gatewayType and instanceName are not found in the system.

Configuration

To use the Akana Discovery Service, you must first configure the connection credentials for the target Akana instance. This is managed by the LbConnectorCredentialService.

Connector Credentials

The following credential fields are required for an akana connector instance:

Troubleshooting

When a discovery run fails or encounters issues, it records errors in the DiscoveryResult object. The following error codes and messages may appear:

If runDiscovery throws an LbConnectorCredentialService.NotFoundException, it means no credentials have been configured for the provided gatewayType: 'akana' and instanceName.

See Also

• Akana Product Documentation:
  • Product Page
  • Atmosphere API Guide
  • API Gateway Documentation
• Related Components:
  • See the guide on managing connector credentials to configure access to your Akana instance.

All SOAP-to-REST docs