Create your first Soap API

Creating a Soap API

API Gateway provides the ability to view, create, and manage SOAP APIs, and publish the APIs to a configured destination for consumption. This section describes how you can create your first SOAP API in API Gateway.

What is a SOAP API?

Simple Object Access Protocol (SOAP) is a messaging protocol that enables users to view and manipulate resources in a standard and secure way. A SOAP API provides a web service to perform operations (such as create, read, update, and delete) on the resources. The data is typically exchanged in XML format. Web Services Description Language (WSDL) is an XML-based language for describing web services. The WSDL document describes the endpoints, operations, data types in the SOAP message, protocol, and data format for each operation. The WSDL document contains the following elements: types, message, portType, and binding.

A SOAP message is an XML document containing the following elements:

• An envelope element - Identifies the XML document as a SOAP message
• A header element - Contains header information
• A body element - Contains call and response information
• A fault element - Contains errors and status information

Why you may still be using SOAP APIs in your organization?

A few reasons you may still be using SOAP APIs in your system:

• Legacy systems might support only XML
• Requirement to support multiple modes of transport such as HTTP, HTTPS, SMTP, JMS
• Lack of support for other content types but just XML
• Supports WSS (Web Services Security) and SSL
• Built-in ACID (Atomicity, Consistency, Isolation, Durability) compliant transactions providing data reliability, safety, and privacy

Creating SOAP API using Import Option

In API Gateway, you can create SOAP APIs by importing it in two ways:

• Using file
• Using URL

Creating a SOAP API by importing an API from a file

Before you begin

Ensure that you have

• Downloaded the SOAP API file with WSDL specifications.

• Manage APIs or Activate / Deactivate APIs functional privilege.
  

  Note

  If you are an Administrator, you would have this privilege.

To create SOAP API by importing an API from a file

Let’s look at a sample scenario, where you are creating a SOAP API by importing the numberconversion.wsdl file.

1. Download numberconversion.wsdl from https://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL.

2. Click APIs in the title navigation bar.

3. Click Create API.

4. Select Import API from file.

   

5. Click Browse and select the numberconversion.wsdl file.

6. Click Open.

   Note

   Based on the specification used in the imported file, API Gateway auto populates the Type field. SOAP API supports the WSDL specifications.

7. Provide the API name as NumberConverter in the Name field.

   • If you provide an API name, API Gateway overwrites the API name specified in the uploaded file.
   • If you do not provide an API name, the API Gateway retains the API name mentioned in the uploaded file.
   • If you do not provide an API name and the uploaded file does not have an API name, then the API name is displayed as Untitled.

8. Provide the version number as 1.0 in the Version field.

9. Select the Type as WSDL since the imported NumberConverter API is a WSDL file.

10. Provide the description as Converts numbers to word or dollars in the Description field.

11. Select the team as TestAPITeam for which you want to assign the NumberConverter API in the Team field.

    Note

    This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User management functional privilege, all teams are displayed. You can select more than one team.

12. Click Create.
    The NumberConverter API is created with the following operations:
    a. NumberToDollars
    b. NumberToWords

    

13. Now that you have created the NumberConverter API, you can check whether it is imported properly by using any of the API testing tools. To know more about how to test the SOAP API, see Testing SOAP API.

Next steps

Now that you have created the SOAP API, you must

• Activate the API. To know more about how to activate the API, see Activating API section.
• Enforce policies based on your business requirement. To know more about how to enforce policies, see Policies.
• Publish the API. To know more about how to publish the API, see Publish APIs.

Creating a SOAP API by importing an API from a URL

Before you begin

Ensure that you have

• The URL from where you want to import the API

• Manage APIs or Activate / Deactivate APIs functional privilege
  

  Note

  If you are an Administrator, you would have this privilege.

To create a SOAP API by importing an API from a URL

Let’s look at a sample scenario, where you are creating the Calculator SOAP API by importing from the http://www.dneonline.com/calculator.asmx?wsdl URL.

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import API from URL.

   

4. Provide the URL as http://www.dneonline.com/calculator.asmx?wsdl

   Note

   As the provided URL is public, you do not have to select the Protected check box. If you have given the restricted access URL and if the URL is password protected, then you must select the Protected check box. After you select the Protected check box, API Gateway displays the Username and Password fields. Make sure you provide the login credentials of the given restricted access URL. Based on the specification used in the imported file, API Gateway auto populates the Type field. SOAP API supports the WSDL specifications. As the http://www.dneonline.com/calculator.asmx?wsdl URL is a WSDL file, API Gateway, by default, selects the file type as WSDL.

5. Provide the API name as Calculator in the Name field.

   • If you provide an API name, API Gateway overwrites the API name specified in the uploaded file.
   • If you do not provide an API name, the API Gateway retains the API name mentioned in the uploaded file.

6. Provide the version number as 1.0 for the Calculator API in the Version field.

7. Select the Type as WSDL since the imported Calculator API URL references a WSDL file.

8. Provide the description as Performs basic calculations on the numbers provided in the Description field.

9. Select the team as TestAPITeam for which you want to assign the Calculator API in the Team field.

   Note

   This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User management functional privilege, all teams are displayed. You can select more than one team.

10. Click Create. The Calculator API is created with the following operations:

    • Add
    • Divide
    • Multiply
    • Subtract

    

11. Now that you have created the Calculator API, you can check whether it is imported properly by using any of the API testing tools. To know more about how to validate the SOAP API, see Testing SOAP API.

Next steps

Now that you have created the SOAP API, you must

• Activate the API. To know more about how to activate the API, see Activating API section.
• Enforce policies based on your business requirement. To know more about how to enforce policies, see Policies.
• Publish the API. To know more about how to publish the API, see Publish APIs.

Testing a SOAP API

Testing the imported SOAP API using SOAPUI

You can test the SOAP API by invoking the API from SOAPUI. SOAPUI is just one example of a third-party SOAP test client.

Let’s test the NumberConverter SOAP API, which was imported using a file. In this example, with the imported SOAP API, you can convert a number to the word format.

To test the SOAP API using SOAPUI

1. In the SOAPUI, select SOAP in the menu bar.

2. In the New SOAP Project, add the following fields:

   • Project Name = Your_Project_Name

   • Initial WSDL field = Value in the Documentation > Artifacts fields in API Gateway

   • Select the Create Requests field

   • Click OK

3. Select Projects > Your_Project_Name > NumberConversionSOAPBinding > NumberToWords > Request1

4. Add a number 25 in the placeholder marked by ?

5. In the Authorization tab, select the type as Basic and provide the login credentials of the API Gateway instance.

6. Click Run.

7. The SOAP API is invoked successfully and returns the status code as 200. The number is displayed in words in the response body.

   

Testing the imported SOAP API using curl

You can test the SOAP API by invoking the gateway endpoint in the curl. SOAP messages must be specified completely as curl is a tool for transferring data from or to a server using any of the following protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET or TFTP. Let’s test the NumberConverter SOAP API, which was imported using a file. In this example, with the imported SOAP API, you can convert a number to the word format.

To test the SOAP API using curl

1. Start the command prompt.

2. Add the following request body in a file as curl is a tool to transfer data from or to a server without SOAP support. Therefore, messages must be specified completely.

3. Save the file as c:\Test\curl-test.xml.

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.dataaccess.com/webservicesserver/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:NumberToWords>
         <web:ubiNum>25</web:ubiNum>
      </web:NumberToWords>
   </soapenv:Body>
   </soapenv:Envelope>
   

   Note

   You can copy the XML content in the soapenv:Body from the either of the following: API Gateway > Operations > NumberToWords > SOAP11 > Input Message OR API Gateway > Operations > NumberToWords > SOAP12 > Input Message

4. In the command prompt, run the following command.

   curl -v -H "Content-Type: text/xml; charset=utf-8" -d @ c:\Test\curl-test.xml -X POST http://hostname:5555/ws/NumberConverter/1.0
   

5. The SOAP API is invoked successfully and returns the status code as 200. The number converted into words is displayed in the response body.