Example: Using the platform REST APIs to publish a product containing a SOAP API

Review this sample scenario to see how you can use the API Connect platform REST APIs to publish a product that contains a SOAP API.

This example demonstrates how to format a request to publish the product, and includes sample files that illustrate the product definition, the API definition, and the SOAP API's WSDL description.

Using the Catalogs API

Publish the product using the API Connect platform Catalogs API:

  • To publish a product to a catalog, use the following syntax:
    POST catalogs/{org}/{catalog}/publish
  • To publish a product to a space within a catalog, additionally specify the space with the following syntax:
    POST catalogs/{org}/{catalog}/{space}/publish

The payload in both cases is a multipart, form-encoded body containing three required parts and one optional part:

  • (Required) A part named product with media type application/yaml or application/json, containing the yaml or JSON source for the product to be published.
  • (Required) One or more occurrences of a part named openapi with media type application/yaml or application/json, containing the YAML or JSON source for each API in the product.
  • (Required for SOAP APIs) One or more occurrences of a part named wsdl with media type application/wsdl, application/wsdl+xml, text/xml, or application/zip containing the WSDL definitions (and referenced XSD files if applicable) associated with the API content.
  • (Optional) A part named gateway_service_urls with media type application/yaml or application/json which is a YAML or JSON array of URLs to specify a subset of the configured gateway services within the catalog or space as publish targets. These URLs can be obtained using the following calls:
    • For a catalog:
      GET /api/catalogs/{org}/{catalog}/configured-gateway-services
    • For a space:
      GET /spaces/{org}/{catalog}/{space}/configured-gateway-services

Within the product content, the form of the references to APIs in the apis section is significant. Each API reference must use the name property instead of the $ref form that may appear in other situations. Here is an example showing a product that refers to the API globalweather version 1.0.0 in the correct form:

info:
  version: 1.0.0
  title: GlobalWeatherProduct
  name: globalweatherproduct
plans:
  ...
apis:
  globalweather1.0.0:
    name: globalweather:1.0.0
...

Example publish operation using cURL

This example publishes a product containing a SOAP API to the Sandbox catalog of the onlinebanking provider organization, using the curl -F option to create a set of form-encoded payload parts and the @ prefix to read the content for each part from a file. Note the part name (product, openapi, wsdl) and the content type of each part given by the type= value.

In this example, the access token has been retrieved earlier and placed in an environment variable named TOKEN. The command is split onto multiple lines for ease of reading but must be entered as a single line.

Request:

curl -v -k 
  -F "product=@globalweatherproduct_1.0.0.yaml;type=application/yaml" 
  -F "openapi=@globalweather_1.0.0.yaml;type=application/yaml" 
  -F "wsdl=@globalweather.wsdl;type=application/wsdl" 
  -H "Authorization: Bearer $TOKEN" 
  -H 'Content-Type: multipart/form-data' 
  -H 'Accept: */*' https://dev.apic.example.com/api/catalogs/onlinebanking/sandbox/publish

Response:

201 Created

{
    "type": "product",
    "api_version": "2.0.0",
    "id": "d03129a4-9a99-4c88-85e6-d51bbf312164",
    "name": "globalweatherproduct",
    "version": "1.0.0",
    "title": "GlobalWeatherProduct",
    "state": "published",
    "scope": "catalog",
    "gateway_types": [
        "datapower-api-gateway"
    ],
    "billing_urls": [],
    "api_urls": [
        "https://dev.apic.example.com/api/catalogs/87227774-d297-4064-8908-b8f0b1db71a5/1bc8f4ba-4178-4a4b-93e8-96a8ca9667fd/apis/d5986b78-d556-4457-8c38-951c471f57fc"
    ],
    "gateway_service_urls": [
        "https://dev.apic.example.com/api/catalogs/87227774-d297-4064-8908-b8f0b1db71a5/1bc8f4ba-4178-4a4b-93e8-96a8ca9667fd/configured-gateway-services/a416f39d-39e1-484c-9f7e-4a599abefec8"
    ],
    "oauth_provider_urls": [],
    "plans": [
        {
            "title": "Default Plan",
            "name": "default-plan",
            "apis": [
                {
                    "id": "d5986b78-d556-4457-8c38-951c471f57fc",
                    "name": "globalweather",
                    "title": "GlobalWeather",
                    "version": "1.0.0",
                    "url": "https://dev.apic.example.com/api/catalogs/87227774-d297-4064-8908-b8f0b1db71a5/1bc8f4ba-4178-4a4b-93e8-96a8ca9667fd/apis/d5986b78-d556-4457-8c38-951c471f57fc"
                }
            ]
        }
    ],
    "visibility": {
        "view": {
            "type": "public",
            "enabled": true
        },
        "subscribe": {
            "type": "authenticated",
            "enabled": true
        }
    },
    "task_urls": [],
    "created_at": "2021-12-15T07:35:40.295Z",
    "updated_at": "2021-12-15T07:35:40.295Z",
    "org_url": "https://dev.apic.example.com/api/orgs/87227774-d297-4064-8908-b8f0b1db71a5",
    "catalog_url": "https://dev.apic.example.com/api/catalogs/87227774-d297-4064-8908-b8f0b1db71a5/1bc8f4ba-4178-4a4b-93e8-96a8ca9667fd",
    "url": "https://dev.apic.example.com/api/catalogs/87227774-d297-4064-8908-b8f0b1db71a5/1bc8f4ba-4178-4a4b-93e8-96a8ca9667fd/products/d03129a4-9a99-4c88-85e6-d51bbf312164"

The request specifies three files, which are included with this example for reference: