Mastering API Calls in Python: SOAP, REST, and GraphQL Explained

In the world of software development, an API (Application Programming Interface) is an omnipresent tool that enables communication and data exchange between different systems. Without APIs, many applications would not work as expected.

Python has become one of the best languages for handling APIs. Whether fetching weather data, sending emails, or building large systems that connect multiple services, Python can easily manage API calls and traffic. Understanding how APIs work and the different types—SOAP, REST, and GraphQL—is essential, as each type offers unique advantages and communication methods.

Below we explore these three API types and demonstrate how to interact with them using Python.

What is SOAP?

SOAP stands for Simple Object Access Protocol. It is a protocol designed for program-to-program communication over a network using XML.

SOAP messages are strict and structured, consisting of an envelope with a header and a body. The header stores metadata, while the body contains the actual data or instructions.

SOAP relies on standards such as WS‑Security (for security) and WSDL (Web Services Description Language, which describes the offered services).

SOAP APIs typically run over HTTP, but they can also use other protocols like SMTP.

Interacting with SOAP in Python

Python developers usually use the zeep library to work with SOAP APIs.

First, install the zeep library:

<code>pip install zeep</code>

Here is a simple SOAP call example:

<code>from zeep import Client
wsdl_url = 'http://www.dneonline.com/calculator.asmx?WSDL'
client = Client(wsdl=wsdl_url)
result = client.service.Add(intA=5, intB=10)
print("Result:", result)
</code>

This example connects to a public calculator service that receives two integers and returns their sum. SOAP APIs require strict structure; missing a detail can cause the request to be rejected.

What is REST?

REST stands for Representational State Transfer. It is an architectural style rather than a strict protocol. RESTful APIs use HTTP methods to perform operations.

Main operations correspond to HTTP verbs:

GET : retrieve data

POST : create new data

PUT : update existing data

DELETE : delete data

Data exchanged between client and server is usually in JSON format, though XML or other formats can also be used. REST APIs are simple, flexible, and scalable, which explains their popularity.

Interacting with REST in Python

The most popular choice for handling REST APIs in Python is the requests library.

First, install the requests library:

<code>pip install requests</code>

Below is a basic GET request example:

<code>import requests
url = 'https://jsonplaceholder.typicode.com/posts/1'
response = requests.get(url)
if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print("Request failed, status code:", response.status_code)
</code>

And here is a POST request example:

<code>import requests
url = 'https://jsonplaceholder.typicode.com/posts'
payload = {
    'title': 'Python and APIs',
    'body': 'Learning how to use REST APIs',
    'userId': 1
}
response = requests.post(url, json=payload)
if response.status_code == 201:
    data = response.json()
    print(data)
else:
    print("Request failed, status code:", response.status_code)
</code>

Compared to SOAP, REST APIs are more tolerant; missing a field may not cause the request to fail, but the response might not behave as expected.

What is GraphQL?

GraphQL is an API query language developed by Facebook to address some limitations of REST APIs.

Unlike REST, where you often receive too much or too little information, GraphQL lets the client request exactly the data it needs.

GraphQL APIs expose a single endpoint. Instead of multiple endpoints for different resources, you specify the desired data through a query.

GraphQL is highly efficient, especially for applications that need to work over limited bandwidth or require flexible data retrieval.

Interacting with GraphQL in Python

You can also use the requests library to work with GraphQL.

Example:

<code>import requests
url = 'https://countries.trevorblades.com/'
query = """
{
  country(code: "BR") {
    name
    capital
    currency
  }
}
"""
response = requests.post(url, json={'query': query})
if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print("Query failed, status code:", response.status_code)
</code>

This example queries information about Brazil. Note that although we use the POST method, we are retrieving data; GraphQL queries are sent via HTTP POST because they include the query payload.

Many public GraphQL APIs are available for exploration, such as https://countries.trevorblades.com/.

SOAP, REST, and GraphQL: Key Differences

Structure : SOAP uses a strict XML format; REST is flexible, usually JSON; GraphQL uses a single query language.

Complexity : SOAP can be complex and verbose; REST is simple and resource‑oriented; GraphQL is powerful but requires understanding of queries and schemas.

Use Cases : SOAP is common in enterprise environments like banking; REST fits almost any web service need; GraphQL shines when clients need precise control over the data they receive.

Error Handling : SOAP provides standardized error codes within its envelope; REST relies on HTTP status codes; GraphQL returns a consistent JSON structure even in error cases.