SOAP API

Panel Discussion: API Security in DevSecOps. Watch the Recording

Home

Akto Academy

SOAP API

Luke Stephens

What is SOAP?

SOAP (Simple Object Access Protocol) is a messaging protocol for exchanging structured information in the implementation of web services. It acts as a messenger between applications. In simpler terms, think of SOAP as a courier that delivers messages between distant applications.

SOAP is XML-based, meaning it uses XML (eXtensible Markup Language) to encode its messages, and it can be carried over a variety of lower-level protocols, including the common HTTP (used in web browsers) and SMTP (used for email). Its primary purpose is to ensure programmatic functionality for web services, emphasizing extensibility, neutrality, and independence.

Learn the difference between SOAP and REST.

Principles of SOAP API

Extensibility: SOAP can be extended to accommodate various requirements, including security, transaction management, and more. This adaptability means it can grow and change according to needs.
For instance, consider this example:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header>
    <!-- Security tokens or other metadata can be added here -->
  </Header>
  <Body>
    <!-- Actual message data goes here -->
  </Body>
</Envelope>

In this SOAP message, the Header element can be customized to contain extended information like security tokens, while the Body holds the message's primary content.

Neutrality: SOAP is like a universal translator. It can operate over any protocol or transport layer, meaning it isn't tied to just one way of sending and receiving data. This includes HTTP, SMTP, and even more.
Independence: SOAP is versatile. It can be utilized with any programming model or language, ensuring interoperability between diverse systems. For instance, a SOAP message created in Java can be understood by a system using Python.

Why SOAP API?

At first glance, SOAP may seem like a complex structure of XML tags. However, its design emphasizes robustness, ensuring reliability and security for mission-critical applications.

Benefits of SOAP API

Standardized: SOAP provides a clear protocol and standard for exchanging messages, ensuring a consistent approach across different platforms. This means less room for error and smoother communication.
For instance, a SOAP message to retrieve user information might uses a consistent format, like this example:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <getUserInfo xmlns="http://example.com/userinfo">
      <userId>12345</userId>
    </getUserInfo>
  </Body>
</Envelope>

Regardless of where it's coming from, the structure remains the same, ensuring it's always understood.

Reliable: Ever worried about a message not getting through? SOAP's built-in features, like message acknowledgment and retry logic, make sure messages are delivered reliably.
Secure: SOAP doesn't disappoint. With built-in security standards like WS-Security, SOAP provides a comprehensive security model. This ensures that the messages are only accessible to intended recipients and remain unaltered during transit.

How does SOAP API Work?

Much like when you send a letter and await a response, SOAP operates as a request-response mechanism:

Client Sends a Request
Just as you'd pen a letter, clients formulate a SOAP message and send it to request specific operations. It's like asking a question.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <getUserInfo xmlns="http://example.com/userinfo">
      <userId>12345</userId>
    </getUserInfo>
  </Body>
</Envelope>

Server Processes the Request
Upon receiving the message (or question), the server processes the SOAP message, interprets the XML, and takes action. It's like the server is reading your letter and preparing a reply.
Server Sends a Response to the Client
Finally, the server sends back a response, much like receiving a reply to your letter. This message contains the answers or results.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <getUserInfoResponse xmlns="http://example.com/userinfo">
      <userName>John Doe</userName>
      <userEmail>john.doe@example.com</userEmail>
    </getUserInfoResponse>
  </Body>
</Envelope>

Components of a SOAP Message

Imagine a SOAP message as a package. Each part of the package has a specific role, ensuring clarity and consistency in delivery:

Envelope: This is the package's outermost layer or wrapper. It holds everything inside and ensures the message is recognized as a SOAP message.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  ...
</Envelope>

Header (Optional): Think of this as the special instructions on a package. This section contains any optional attributes of the message that might be needed for its processing, like authentication details.

<Header>
  <!-- Special instructions or details, like security tokens -->
</Header>

Body: The Body is the main content of the package. It carries the actual message or the core information.

<Body>
  <!-- The heart of the message -->
</Body>

Fault (Optional): Sometimes, things go wrong. Within the Body, a Fault element can highlight errors that occurred during processing, acting as an error message.

<Fault>
  <faultcode>Server</faultcode>
  <faultstring>Server Error</faultstring>
</Fault>

SOAP Fault Handling

Mistakes happen. SOAP's built-in error handling mechanism, "SOAP Faults," shines a light on these errors, offering clarity on what went wrong:

Fault Codes: Think of these as error categories. SOAP defines a few basic fault codes to quickly identify the type of error, making troubleshooting smoother.

<faultcode>Client</faultcode>

Fault String: This is a brief explanation of the fault. It provides a human-readable description, much like an error pop-up on your computer.

<faultstring>Invalid message format</faultstring>

Detail: Just as a doctor provides specifics after a general diagnosis, the optional Detail element provides application-specific error information.

<detail>
  <errorcode>1001</errorcode>
</detail>

Example of SOAP API

Let's bring SOAP into a familiar scenario: the "To-Do List" application. SOAP can be used to manage tasks between a client and server, ensuring clear and secure communication for each task operation:

SOAP Methods in Action

listTasks: Viewing All Tasks

This method retrieves all tasks stored in the database. Think of this as checking your task list in a to-do app, where the application sends a request to fetch all your tasks.

Request:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <listTasks xmlns="http://example.com/tasks"/>
  </Body>
</Envelope>

Response:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <listTasksResponse xmlns="http://example.com/tasks">
      <task>
        <id>1</id>
        <title>Buy groceries</title>
      </task>
      <task>
        <id>2</id>
        <title>Walk the dog</title>
      </task>
    </listTasksResponse>
  </Body>
</Envelope>

Conclusion

SOAP serves as a foundational protocol for web service communication, emphasizing reliability, security, and extensibility. When you think of SOAP API, envision a reliable courier, ensuring your messages are securely and consistently delivered, regardless of where they're coming from or going to.

Next lesson

Next Lesson: GraphQL vs REST

Next lesson

Next Lesson: GraphQL vs REST

Next lesson

Next Lesson: GraphQL vs REST

What is SOAP?

Principles of SOAP API

Why SOAP API?

Benefits of SOAP API

How does SOAP API Work?

Components of a SOAP Message

SOAP Fault Handling

Example of SOAP API

SOAP Methods in Action

Conclusion

On this page