SOAP APIs

Integration allows you to trigger project workflows and Flow services through API endpoints, add custom APIs or export existing ones, link them with your project workflows and Flow services, and then make API requests to execute the associated workflows and Flow services.

Creating SOAP APIs

Web services are building blocks for creating open, distributed systems. A web service is a collection of functions that are packaged as a single unit and published to a network for use by other software programs. For example, you could create a web service that checks a customer’s credit or tracks delivery of a package. If you want to provide higher-level functionality, such as a complete order management system, you could create a web service that maps to many different flows, each performing a separate order management function.

A SOAP API defines a web service and it encapsulates all the information of a web service. The SOAP API contains the message formats, data types, transport protocols, and transport serialization formats that is used between the consumer (requester) and the provider of the web service. In essence, the SOAP API represents an agreement governing the mechanics of interacting with that service.

Integration allows you to write integration logic to integrate different types of connectors. This logic can be exposed to the external world using SOAP APIs. A SOAP API is a service provided to external users.

An operation is the WSDL element that exposes some functions of a web service and defines how data is passed back and forth. A SOAP API exposes one or more Flow service as operations, so each operation in a SOAP API corresponds to a Flow service. The input for the Flow service corresponds to the request body for the operation. The output of the flow is the response body for the operation.

You can create SOAP APIs from scratch or by using a WSDL file. A SOAP API exposes one or more Flow services as operations, so each operation in a SOAP API corresponds to a Flow service.

How it Works

  1. From the Integration navigation bar, click Projects.
  2. Select a project and then click APIs > SOAP API.
    3. The SOAP APIs page appears.

  3. From the SOAP APIs page, click Create API. A new API page appears.

    4. You can create an API in one of the following methods:

    Create a new SOAP API from scratch

    1. On clicking this option, click Next. The Basic Info page appears.

    2. Fill in values for the fields as per the instructions given below:

      Field Description
      Name Provide a suitable name for the API. For example, Soap_api_test1.
      Description Provide a short description for the API.
      Version Choose whether SOAP messages for this SOAP API should use SOAP 1.1 or SOAP 1.2 message format. For example, let us use SOAP 1.1.
      Access Mark the SOAP API as Public or Private.

      Note
      To enable the execution of an API from the IBM webMethods API Gateway, you can use the Internal URL under the API Endpoints, which is displayed on the SOAP API page.

      Support for domains with-internal will soon be deprecated, so you must reconfigure the alias in IBM webMethods API Gateway by using the Internal URL provided under API Endpoints on the REST or SOAP API details page.

      In an existing API, when you change the selected value for the Access field from Private to Public or Public to Private, the changes may take a while to propagate for the ongoing API executions.|
      Use and style for operations A WSDL SOAP binding can be either a document style binding or a Remote Procedure Call (RPC) style binding. A SOAP binding can also have a literal or an encoded use. Select the use/style for operations in the SOAP API:
      - Document - Literal
      - RPC - Literal
      - RPC - Encoded
      Let us select Document - Literal as example.
      Select Flow service Displays all the Flow service available in the selected project. Select a Flow service to use as an operation. The operation signature becomes the input and output messages for the operation in the WSDL document. For example, let us select “AddInts”.
      Enforce WS-I Basic Profile 1.1 compliance Select this option if you want Flow services to validate all the SOAP API objects and properties against the WS-I requirements before creating the SOAP API.
      Validate schema using Xerces Flow service automatically uses an internal schema parser to validate the schemas associated with the XML Schema definition. Select this option if you want Flow services to also use the Xerces parser to validate the schemas associated with the XML Schema definition. However, the Xerces parser provides stricter validation. As a result, some schemas that the internal schema parser considers to be valid might be considered invalid by the Xerces parser.

    3. Click Save.

      4. With this, you have successfully created and saved an API for your project.

      Create API by importing API from a specified file

      1. Select the Import API / I have an existing API option, click Browse, import a WSDL file, and click Next. If you want to add separate elements of a service definition after import, such as WSDLs, XSDs, and/or XMLs to the primary WSDL, click Browse file(s) or use the drag and drop functionality. You can select one or multiple dependent WSDLs, XSDs, and/or XMLs to the primary WSDL. Ensure that you add the primary WSDL as the first WSDL, and then add separate elements of the service definition, for example, dependent WSDLs, XSDs, and/or XMLs to the primary WSDL.

        The Build a SOAP API with WSDL page appears.

      2. Next, fill in the values for the fields as per the instructions given below:

        • Name - Provide a suitable name for the API you want to create. For example, let us use Soap_api_test2 as the API name.
        • Description - Provide a short description for this API.
        • Content model compliance - Under Content model compliances, select a content model compliance to indicate how strictly Integration represents content models from the XML Schema definition in the resulting document type. Let us select the option None.

      3. Click Save.

        With this, you have successfully imported and saved an existing API for your project.

        Import API using URL

        1. On selecting this option, click Next, The Basic Info page appears.

        2. Next, fill in values for the fields as per the instructions given below:

          • Name - Provide a suitable name for the API you want to create. For example, Soap\_api\_test3.
          • Description - Provide a short description for this API.
          • WSDL URL - Provide a valid WSDL URL that can be accessed over a network. For example, https://graphical.weather.gov/xml/DWMLgen/wsdl/ndfdXML.wsdl.
          • User Name - Enter a username to access the WSDL URL.
          • Password - Enter a password to access the WSDL URL.
          • Content model compliance - Under Content model compliances, select a content model compliance to indicate how strictly Integration represents content models from the XML Schema definition in the resulting document type. Let us select None.

        3. On filling in the details, click Save.

          With this, you have successfully imported and saved an API using URL for your project.

          You can now view all the SOAP APIs that you created under SOAP APIdetails page.

          You can edit, delete, and copy a SOAP API from the SOAP API details page. The Action(s) column displays the edit , delete , and copy icons.

          • To edit an existing SOAP API, on the SOAP APIs page, click the edit icon.
          • To delete an existing SOAP API, on the SOAP APIs page, click the delete icon.
          • To copy a SOAP API, select a SOAP API, and click the copy icon . The Copy dialog box appears.
            • Select a project from the drop-down list.
            • Type a new name in the Name field.
            • Click Save.

          The system creates a copy of the SOAP API with the new name and it appears in the SOAP APIs page of the target project.

          If you create a SOAP API by using a WSDL file, a copy of the SOAP API (including its dependencies namely its Flow services, Document Types, and Operations) is created. When Flow services encapsulated by the copied SOAP API are modified, the changes are reflected only in the copied SOAP API and not in the SOAP API from which it was copied. This is because, if you have created a SOAP API using the Import API approach, each SOAP API has its own set of Flow services.

          If you create a SOAP API by using an existing set of Flow services (Create from scratch), a copy of the SOAP API is created. You can type a new name at the time of copying and a SOAP API with the new name is created. The same Flow services that are referred to in the original SOAP API are also referred to in the copied SOAP API (provided it is copied in the same project). If the referred Flow service is modified in the copied SOAP API, then the changes will reflect in the original SOAP API because both the SOAP APIs refer or point to the same Flow services (This does not happen when the Create from scratch SOAP API is copied to a different project as the referenced Flow services are also copied to the target project). However, if another operation with a different Flow services is added to the copied SOAP API, this does not show in the original SOAP API.

          To view the API details page, click the SOAP APIs name link. You will then be redirected to the API details page.

          On the API details page, you can view the WSDL document associated with the SOAP API. The displayed WSDL document contains all the information to invoke the operations described in the WSDL. For a SOAP API created from a WSDL that contains relative URIs that are anonymously addressable, Integration replaces any relative URIs with an absolute URI using the base URI of the WSDL file.

          Click the Operations tab to go to the Operations page. Integration uses the operation definitions from the WSDL to generate a Flow service for each operation in the WSDL.

          Note
          • You cannot add operations in a SOAP API created from a WSDL. Also, you cannot delete operations from a SOAP API created from a WSDL.
          • Flow services generated automatically using WSDL URL or WSDL file (SOAP APIs) are not listed in the project folder or under Monitor page filters. You can access these Flow services by going to:

            SOAP APIs > Operations > Operation name > Flow service name.

            The project folder is designed to facilitate business logic addition, so operations such as restart, resume, and resubmit are unavailable there.