Skip to content

Onboard SOAP API

Overview

The Yappes SOAP API onboarding allows you to integrate and manage SOAP-based web services within the Yappes Enterprise API Manager platform, enabling you to achieve seamless API governance and deployment across your organization.

This powerful feature transforms traditional SOAP services into managed APIs that can be monitored, secured, and scaled through the Yappes platform's comprehensive API management capabilities.

By leveraging the SOAP API onboarding feature, you can quickly configure legacy SOAP services, add custom operations, define headers and response schemas, and deploy APIs with enterprise-grade reliability.

The streamlined onboarding process eliminates the complexity traditionally associated with SOAP service integration, allowing you to focus on delivering business value rather than wrestling with technical configurations. Whether you're modernizing legacy systems or integrating with partner services that still rely on SOAP protocols, this feature provides a bridge between traditional web services and modern API management practices.

Prerequisites

Before beginning the SOAP API onboarding process, ensure you have:

  • Active Yappes Enterprise Account: Valid credentials for the Yappes Enterprise API Manager platform
  • Required Permissions: API management and deployment privileges within your organization
  • SOAP Service Details:
  • Host URL of your SOAP service
  • Service name and operation details
  • SOAP version (1.1 or 1.2) being used
  • Any required headers or authentication parameters
  • Publishing Path: A unique gateway-facing path prefix (e.g. /public) for the API
  • API Logo (jpeg or png only). Optional but recommended.
  • Marketplace Tags. (Create one if not already.)
  • TLS Certificates. (Create one if not already.) Optional.

Step-by-Step Implementation

Step 1: Navigate to My APIs

  • Locate Manage APIs → My APIs in the main navigation menu
  • The system will display your existing APIs (if any)

Navigate to My APIs

Step 2: Initiate API Onboarding

  • Click the Onboard API button to start the onboarding process
  • The API onboarding interface will open, presenting you with API type options

Initiate API Onboarding

Step 3: Select SOAP as API Type

  • In the API Type* dropdown field, click to see available options
  • Select SOAP from the list of API types
  • The form will update to show SOAP-specific configuration fields

Step 4: Configure Basic API Information

  • In the API Name* field, enter a descriptive name for your API
  • In the API Host Url* field, enter the complete host URL of your service
  • In the Base Path* field, enter the base path
  • In the Publishing Path* field, enter the gateway-facing path prefix (e.g. /public); it must be unique across all platform APIs
  • Optionally enter a Description
  • The combination of host URL and base path forms your upstream endpoint; Publishing Path defines how consumers reach the API on the gateway

Step 5: Save Initial Configuration

  • Review all entered information for accuracy
  • Click the Save button to store your API configuration
  • A confirmation message should appear indicating a successful save

Step 6: Configure Upstream Servers, TLS, Logo, and Tags

After saving, additional sections appear for upstream servers, logo, and tags.

Configure Upstream Servers

  • Go to Configure Upstream Servers and define URLs for Development, Testing, and Production using Development API Host Url, Testing API Host Url, and Production API Host Url.
  • The Testing environment shows a Default Publishing Environment sub-label.
  • Click Update when done.

Configure TLS (optional)

  • Click Configure TLS for the environment where you want to attach a certificate.
  • In the SSL/TLS Certificates popup, select the cert type: PFX P12 or Cert Key CA.
  • Select the shared resource(s) for the certificate, key, and CA as applicable.
  • Click Save.

Info

Configuring TLS requires authorized certificates. If you haven’t created one, see Shared Resources.

API Logo and Marketplace Tags

  • Go to API Logo and click Upload to add a logo (jpeg, jpg, or png; less than 1MB).
  • Go to Marketplace Tags, search, and select tags for discoverability.

Info

If no marketplace tags exist, create one in Marketplace Tags.

  • Click Next to proceed to operations.

Add Tags for Organization

Step 7: Add SOAP Operations

You can add SOAP operations in two ways:

  • Option 1: Manual Operation Entry

    • Click the Add button to begin adding operations
    • In the Operation Name* field, enter a descriptive name for the operation
    • This name will be used to identify the specific SOAP operation
    • In the SOAP Version* dropdown, select the appropriate version (typically SOAP 1.1 or SOAP 1.2)
    • In the SOAP Service Name* field, enter the exact service name from your WSDL
    • In the SOAP Action/Operation* field, enter the specific action or operation name
    • Click Add Operations to save this operation configuration

    Add SOAP Operations - Manual Operation Entry

  • Option 2: WSDL Upload

    • Click the Upload button to open a dialog
    • Enter the version
    • Provide either the WSDL file URL or upload the WSDL file directly

    Add SOAP Operations - WSDL Upload

Step 8: Configure Operation Details

After adding a SOAP operation, click on that operation to open its configuration interface.
From here, you can add headers, define form data, define response schemas, and even edit SOAP operation details if needed.

  • Add Required Headers

    • If your SOAP service requires custom headers, click Add Header
    • In the Mandatory field, specify whether the header is required
    • Enter the Header Name* in the designated field
    • Select the Type: choose from string, number, or boolean
    • Enter the Header Value* in the corresponding field
    • Enter a Description (optional) to document the header purpose
    • Click Add to save the header configuration

    Configure Operation Details - Headers

  • Define Form Data

    • Click on the Form Data tab to open the form configuration section

    • Click Add Form Data to define input fields for the SOAP request

    • Configure the form fields as follows:

      • Name*: The parameter name (mandatory)
      • Type*: Disabled; fixed as XML
      • Value*: Must always be entered in XML format
      • Description: Optional field for documenting the parameter

    • Save the form data entry

    Configure Operation Details - Form Data

  • Define Response Schema

    • Click on the Response Schema tab to open the response configuration section
    • Click Add Response Schema to define expected responses
    • In the Name* field, enter a name for the response schema
    • Define the status code (typically 200 for successful responses)
    • Enter or paste the response schema structure as needed

    • Use the Return SOAP Fault switch button if your API needs to handle faults.

    • If enabled (True), you must also provide:

      • Fault Code: Identifier for the SOAP fault
      • Fault String: Descriptive message for the SOAP fault

    Configure Operation Details - Response Schema

Step 9: Complete Optional Configurations

  • After completing your operation details, click the Back button, then click Next

  • You will be presented with several optional configuration steps:

    • README: Add API description or documentation
    • License: Attach license information for your API
    • Rate Plans: Attach or create rate plans for the API during Step 3 onboarding. See Rate Plans and Onboard APIs Step 3.
    • Tryout Quota: Define the number of times an API consumer can use the tryout option
    • Monitor: Enable monitoring for API performance and errors
    • Gateway Load Balancing: Configure load balancing across backend servers for better scalability

  • These steps are optional and can be configured during onboarding or updated later after deployment.

Complete Optional Configurations

Step 10: Publish or Submit for Approval

After completing all configurations, publish or submit the API depending on your role and whether an approval workflow is attached:

Direct publish — If no approval workflow is required, platform-admin or api-product-manager users can click Finish and Publish or Publish from My APIs.

Submit for approval — If an approval Workflow is attached:

  • Click Submit for approval from the API details page or onboarding step three.
  • In the modal, select the change type: Major, Minor, or Patch.
  • Click Submit for approval.

After submission, the button changes to Submitted & approval pending and the My APIs grid shows Approval pending. Approvers act in Pending Approvals. The API remains unpublished until approved.

Submit for Approval

Save without publishing — Click Finish and Exit to save progress and continue later.

Step 11: Manage Your API

  • Navigate back to My APIs to view your API
  • Select the API to view details or make modifications
  • You can monitor, update, publish, or manage the API as needed

Configuration and Settings

Required Configuration Fields

Field Description Example
API Name Unique identifier for your API CustomerService_SOAP
API Host URL Complete URL to your SOAP service https://api.example.com
Base Path Upstream path segment (required) /services/v1
Publishing Path Gateway-facing path prefix (required, unique) /public
SOAP Version Version of SOAP protocol SOAP 1.1 or SOAP 1.2
Service Name Exact service name from WSDL CustomerServiceSoap
SOAP Action/Operation Specific operation to expose GetCustomerDetails

Optional Configuration Fields

Headers Configuration

  • Add authentication headers for secured services
  • Include custom headers required by your SOAP implementation
  • Mark headers as mandatory or optional based on requirements

Response Schema Options

  • Define multiple response schemas for different status codes
  • Support both success (2xx) and error (4xx, 5xx) responses
  • Use JSON or XML schema definitions as appropriate

Basic Functionality Testing

Test Checklist

  • API responds to SOAP requests at the configured endpoint
  • All configured operations are accessible
  • Headers are properly passed through to the backend service
  • Response schemas match actual service responses
  • Error handling returns appropriate SOAP faults

Troubleshooting

Common Issues and Solutions

  • Invalid Publishing Path

    • Issue: "The publishing path must be unique across all platform APIs" error
    • Solution: Choose a different Publishing Path value that is not already in use

  • Operations Not Appearing

    • Issue: Added operations don't show in the list
    • Solution: Ensure all mandatory fields are filled before clicking Add Operations
    • Verify: SOAP version matches your service specification

  • Approval Pending Indefinitely

    • Issue: API remains in Approval pending status
    • Solution: Check if approvers have processed the request in Pending Approvals
    • Action: Contact your platform administrator or approver group

  • Response Schema Validation Errors

    • Issue: "Invalid schema" error when adding response schema
    • Solution: Ensure the schema format matches the expected type (JSON/XML)
    • Tip: Use copy-paste method for complex schemas to avoid formatting issues

Error Messages Reference

Error Message Cause Resolution
"API Name already exists" Duplicate API name Choose a unique name
"Invalid Host URL" Malformed URL Check URL format and protocol
"SOAP Version mismatch" Wrong SOAP version selected Verify with WSDL specification
"Authorization failed" Missing or incorrect headers Add required authentication headers

Pro Tip

Consider creating a test version of your SOAP API first to validate all configurations before deploying to production. This allows you to experiment with different settings without affecting live services.