What is an API? REST vs GraphQL Explained for Developers

The Challenge: Making Software Talk

As an IT engineer, I’ve spent years building systems where different software components must communicate seamlessly. These components often run on separate servers or even entirely different platforms. Consider a mobile app fetching user data from a backend server, or a web application displaying product information from a database. How do these disparate pieces of software understand each other and exchange information reliably?

Inter-application communication presents a fundamental challenge in modern software development. Without a standardized way for systems to interact, every integration would quickly become a custom, brittle mess. This is precisely the problem APIs were designed to solve, and solving it effectively has become more critical than ever.

Core Concepts: Unpacking APIs, REST, and GraphQL

What Exactly is an API?

An API, or Application Programming Interface, is simply a set of rules and definitions. It allows different software applications to communicate with each other. Acting as an intermediary, an API defines the methods and data formats applications can use to request and exchange information.

Imagine ordering food at a restaurant. As the client, you don’t go into the kitchen to prepare your meal. Instead, you consult the menu (the API documentation) to see what’s available. Then, you tell the waiter (the API endpoint) your order. The waiter takes your request to the kitchen (the server), which prepares the food and sends it back to you. You get exactly what you asked for, without needing to know the intricate details of the kitchen’s operations.

In the software world, this means a mobile app can request a list of users from a server. Similarly, a web service can send payment details to a payment gateway. Neither application needs to understand the internal workings of the other; they just need to agree on the API’s contract.

From my real-world experience, mastering APIs is an essential skill. They form the backbone of almost any distributed system you’ll encounter, from microservices architectures to integrating third-party services.

RESTful APIs: The Industry Standard

REST, which stands for Representational State Transfer, is an architectural style for designing networked applications. It’s not a protocol or a standard, but rather a set of constraints. When applied, these constraints result in a simple, scalable, and stateless system.

A RESTful API (often called a REST API) uses standard HTTP methods like GET, POST, PUT, and DELETE to perform operations on resources. Resources are typically identified by unique URLs (Uniform Resource Locators). For example, if you have a collection of ‘posts’, you might interact with them like this:

• GET /posts: Retrieve a list of all posts.
• GET /posts/123: Retrieve the post with ID 123.
• POST /posts: Create a new post.
• PUT /posts/123: Update the post with ID 123.
• DELETE /posts/123: Delete the post with ID 123.

Data is typically exchanged in JSON format, though XML is also common. REST APIs are stateless, meaning each client request to the server contains all the information needed to understand it. The server doesn’t store any client context between requests.

Pros of REST:

• Simplicity: Easy to understand and implement, leveraging existing HTTP methods.
• Widespread Adoption: Benefits from extensive tooling and community support.
• Cacheable: HTTP caching mechanisms can significantly improve performance for GET requests.

Cons of REST:

• Over-fetching/Under-fetching: Clients often receive more data than they need (over-fetching) or must make multiple requests to gather all necessary data (under-fetching).
• Numerous Endpoints: As an application scales, managing many different endpoints can complicate client-side development.

GraphQL: The Query Language for APIs

GraphQL is an open-source data query and manipulation language for APIs, along with a runtime for fulfilling those queries with your existing data. Facebook developed it in 2012 and publicly released it in 2015.

The core idea behind GraphQL is to empower the client to ask for exactly what it needs and nothing more. Instead of multiple endpoints, a GraphQL API typically exposes just a single endpoint. Clients send a query (a string describing their data requirements) to this endpoint, and the server responds with a JSON object containing precisely the requested data.

Let’s revisit the ‘posts’ example. With GraphQL, you might query for posts and their authors, specifying only the fields you need:

query {
  post(id: "123") {
    title
    content
    author {
      name
      email
    }
  }
}

This flexibility allows clients to get all necessary data in a single request. Consequently, it reduces network overhead and improves performance, particularly for mobile applications or complex user interfaces.

Pros of GraphQL:

• Efficient Data Fetching: Eliminates over-fetching and under-fetching. Clients receive exactly what they request.
• Single Endpoint: Simplifies client-side code by interacting with one URL.
• Strongly Typed Schema: Provides a clear contract between client and server, enabling powerful development tools and validation.
• Real-time Capabilities: Built-in support for subscriptions allows clients to receive real-time updates.

Cons of GraphQL:

• Learning Curve: Requires understanding a new query language and schema definition.
• Caching Complexity: Caching can be more intricate than with REST, as requests are not based on standard HTTP URLs.
• File Uploads: Implementing file uploads can be less straightforward compared to REST.
• N+1 Problem: If not implemented carefully, fetching related data can lead to numerous database queries.

REST vs GraphQL: A Direct Comparison

Here’s a quick overview of how these two architectural styles stack up:

Feature	REST	GraphQL
Architecture	Multiple endpoints for different resources	Single endpoint for all data requests
Data Fetching	Fixed data structures per endpoint (over/under-fetching common)	Client specifies exact data needed (no over/under-fetching)
HTTP Methods	Leverages standard HTTP methods (GET, POST, PUT, DELETE)	Primarily uses POST for queries and mutations
Caching	Native HTTP caching support	Requires custom caching solutions or client-side caching
Complexity	Generally simpler for basic use cases	Higher initial learning curve, but more powerful for complex needs
Evolving APIs	Versioning often required for breaking changes	More flexible; clients only break if fields they use are removed
Real-time	Requires WebSockets or polling for real-time updates	Built-in subscriptions for real-time data

Hands-on Practice: Interacting with APIs

Let’s explore some practical examples of how you’d interact with both a REST API and a GraphQL API.

Calling a REST API

We’ll use JSONPlaceholder, a free fake API for testing and prototyping, to demonstrate a simple REST API call. Our goal is to fetch a post by its ID.

Using curl:

curl https://jsonplaceholder.typicode.com/posts/1

Output:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Notice that we received all fields for the post (userId, id, title, body), even though we might only have wanted the title. This illustrates over-fetching.

Using Python requests:

import requests

url = "https://jsonplaceholder.typicode.com/posts/1"
response = requests.get(url)

if response.status_code == 200:
    post_data = response.json()
    print(f"Post Title: {post_data['title']}")
    print(f"Post Body: {post_data['body']}")
else:
    print(f"Error: {response.status_code}")

Querying a GraphQL API

For GraphQL, we’ll query a public API like Countries API (countries.trevorblades.com). We’ll fetch data about a specific country, asking only for the fields we truly need.

Using curl:

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"query": "query { country(code: \"BR\") { name capital emoji } }"}' \
  https://countries.trevorblades.com/

Output:

{
  "data": {
    "country": {
      "name": "Brazil",
      "capital": "Brasília",
      "emoji": "🇧🇷"
    }
  }
}

Here, we explicitly requested the name, capital, and emoji for Brazil. And that’s exactly what we received—no extra data, clearly demonstrating GraphQL’s efficiency.

Using Python requests:

import requests
import json

url = "https://countries.trevorblades.com/"
query = """
query {
  country(code: "BR") {
    name
    capital
    emoji
  }
}
"""

headers = {"Content-Type": "application/json"}
data = {'query': query}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    country_data = response.json().get('data', {}).get('country')
    if country_data:
        print(f"Country Name: {country_data['name']}")
        print(f"Capital: {country_data['capital']}")
        print(f"Emoji: {country_data['emoji']}")
    else:
        print("Country not found or query error.")
else:
    print(f"Error: {response.status_code}")

Conclusion

Understanding how applications communicate through APIs is a cornerstone of modern software development. Both REST and GraphQL offer robust ways to build and consume APIs, each with distinct strengths and weaknesses.

REST, with its simplicity and adherence to HTTP standards, remains an excellent choice for resource-oriented APIs. It’s especially useful when dealing with relatively static data, or when wide client compatibility and caching are paramount. REST is mature, well-understood, and boasts a vast ecosystem.

In contrast, GraphQL shines when client-side flexibility and efficient data fetching are critical. If your application has complex data requirements, frequently evolving UIs, or needs to minimize network requests (e.g., mobile apps), GraphQL can be a fantastic option. It allows clients to dictate their data needs precisely, giving developers more control and reducing the burden of managing many endpoints.

Ultimately, the decision to use REST or GraphQL depends on your project’s specific requirements, your team’s familiarity with the technologies, and the nature of the data you’re exposing.

Many modern applications even employ a hybrid approach, using REST for simpler, resource-based interactions and GraphQL for more complex, client-driven data needs. Both are incredibly valuable tools in an IT engineer’s toolkit, and knowing when and how to apply them effectively is a skill that truly pays dividends.