REST API vs GraphQL: What I Learned as a Beginner Dev

Hey internet. Nowadays, building web and mobile applications means interacting with data, and that's where APIs (Application Programming Interface) come into play. They are the backbone of modern software, allowing different services to communicate seamlessly. For many new developers, the initial encounter with APIs often brings up two prominent terms: REST API and GraphQL.

For a long time, REST (Representational State Transfer) APIs stood as the undisputed standard for building web services. They are robust, widely understood, and power a vast portion of the internet. However, as applications grew more complex and user experiences demanded greater fluidity, certain limitations of REST became apparent. This paved the way for new approaches, and that's where GraphQL entered the scene, offering compelling solutions to many of these challenges.

As a beginner, it was a bit confusing: Which one should I pick? What are the real differences?

This article is all about what I learned trying to figure that out, and what you, as a new developer, might face when choosing between them.

---

REST API: The Familiar Friend

When I first learned about APIs, REST was usually the first one introduced. It's been around for a while and powers a huge chunk of the internet.

What is it?

Think of a REST API as a library where each "book" is a piece of data, called a resource. You access these books using unique addresses (URLs) and perform actions on them using standard "library commands" (HTTP methods like GET, POST, PUT, DELETE).

• GET: "Get me this book." (Fetch data)

• POST: "Add this new book to the library." (Create data)

• PUT: "Update this existing book." (Update data)

• DELETE: "Remove this book." (Delete data)

So, if you wanted to get a list of all users, you might send a GET request to https://jsonplaceholder.typicode.com/users. To get details for a specific user, it might be https://jsonplaceholder.typicode.com/users/1.

Why it felt easy at first (and still does for some things)

1. Simple Concepts: The idea of resources and HTTP methods is pretty straightforward. You map what you want to do (read, create, update, delete) directly to these methods.

2. Everywhere: There are many REST APIs available, along with lots of tutorials and examples. It feels like the standard choice, which is reassuring when you're just beginning.

3. Browser Friendly: Your web browser already understands how to make GET requests (that's how you load most web pages!), which makes testing and understanding quite intuitive.

Where beginners often hit bumps with REST

While it starts simple, I quickly ran into some common frustrations:

1. Over-fetching and Under-fetching

This was probably my biggest headache. Imagine you have a list of users, and you only want their name and email for a summary view. With a typical REST API, you might get all their details: name, email, address, phone number, last login, etc.

// GET /api/users/1 - You only needed name and email, but got everything!
{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "phone": "1-770-736-8031 x56442",
  "website": "hildegard.org",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"
  }
}

This is over-fetching – you get more data than you need, which can slow down your app, especially on slow connections.

The flip side is under-fetching. Let's say you want to display a user's name and all their blog posts. You might first call /api/users/123 to get the user's name, and then call /api/users/123/posts to get their posts. This means multiple requests just for one screen!

// Step 1: Get user details
GET /api/users/123

// Step 2: Get user's posts
GET /api/users/123/posts

These "waterfall" requests can make your app feel sluggish.

2. Managing Many Endpoints

As my projects grow, the number of distinct URLs (endpoints) starts multiplying. It becomes tricky to keep track all of them, and sometimes I'd end up with very specific endpoints just to avoid over/under-fetching.

---

GraphQL: The Promising Newcomer

GraphQL came onto my radar as a potential solution to these exact problems. It's not a replacement for REST in all cases, but it definitely offers a different way of thinking about APIs.

What is it?

Instead of many endpoints, GraphQL usually has just one endpoint. You send a "query" (a request for data) to this endpoint, and you ask for exactly what you need. Think of it like a highly customizable menu where you can order precisely what you want, no more, no less.

Why it felt promising (and often delivers)

1. Ask for Exactly What You Need: This is GraphQL's superpower. You define the shape of the data you want, and the server gives you just that. No over-fetching!

    # This is a GraphQL query
    query GetUserNameAndEmail {
      user(id: "123") {
        name
        email
      }
    }
   

   And the response would look something like this:

    {
      "data": {
        "user": {
          "name": "Alice Wonderland",
          "email": "alice@example.com"
        }
      }
    }
   

   This means fewer requests and faster load times.

2. Get Multiple Resources in One Request: You can ask for a user's name and their posts in a single query, solving the under-fetching problem.

    query GetUserAndPosts {
      user(id: "123") {
        name
        posts {
          title
          content
        }
      }
    }
   

3. Strongly Typed Schema: GraphQL has a schema, which is like a blueprint that defines all the data and operations available. This is fantastic for development because it acts as a contract between your front-end and back-end, making it clear what data you can ask for.

Where beginners often hit bumps with GraphQL

GraphQL definitely has its perks, but it's not a free lunch. I found a few things that made it a bit trickier to get started with:

1. Steeper Learning Curve

You have to learn new concepts:

• Queries: Used for fetching data and Mutations for changing data like creating, updating, or deleting.

• Schemas: You need to understand how to define your data types and relationships in the GraphQL Schema Definition Language (SDL). This is a new language to learn compared to just using existing HTTP concepts.

• Resolvers: On the server side, you need to write functions (resolvers) that tell GraphQL how to get the data for each field in your schema. This adds a new layer of abstraction to grasp.

2. Tooling and Ecosystem Can Feel Overwhelming

While GraphQL has fantastic tools (like Apollo Client for the front-end or GraphiQL for testing queries), setting them up and understanding how they all fit together can take some effort. It's a bit more involved than just sending a fetch request to a REST endpoint.

3. Caching is More Complex

With REST, browsers and CDNs can easily cache responses based on the URL. With GraphQL, because every query can be unique even to the same endpoint, traditional HTTP caching doesn't work as directly. This means you often need to implement more sophisticated client-side caching strategies, which can be a bit advanced for beginners.

---

When to Choose Which (from a beginner's perspective)

After grappling with both, here's my simplified take on when to lean towards one or the other, especially as a beginner:

• Choose REST when...

  • Simplicity is key: You have a small project, clear data needs, and want to get something working quickly with familiar concepts.

  • Learning basics: It's a great way to understand fundamental API concepts, HTTP methods, and status codes before adding the GraphQL layer.

  • Public APIs: Many public APIs you'll interact with are REST-based.

• Choose GraphQL when...

  • Data needs are complex/evolving: Your application needs very specific data for different views, and those needs might change often.

  • Multiple clients: If you're building an API that will be consumed by very different clients (e.g., a web app, a mobile app, a smart device) that all need different subsets of data.

  • Performance is critical (and you know how to optimize): When minimizing requests and payload size is a top priority, and you're ready to learn about optimizing GraphQL queries.

Ultimately, there's no single "best" choice. It really depends on your project's specific needs and your team's comfort level.

---

What I Learned As a Beginner Dev

My journey through REST and GraphQL taught me a few important lessons:

1. Understand the Core Problems: It's not about which is "better," but which solves your specific problems more effectively. REST's over/under-fetching was a real problem that GraphQL aimed to fix.

2. Start Simple, Then Evolve: For my very first API-driven projects, REST felt more accessible. As I understood more about data flow and efficiency, exploring GraphQL became a natural next step. Don't feel pressured to use the "latest and greatest" if it hinders your learning.

3. Tooling Makes a Difference: Good development tools (like VS Code extensions for GraphQL or API testing tools for REST) can dramatically ease your experience with either.

4. Documentation is Your Best Friend: Whether it's a REST API or a GraphQL API, clear and comprehensive documentation makes learning and integrating a breeze.

The world of development is always evolving, and learning about APIs is a continuous journey. My advice? Don't be afraid to experiment! Build small projects with both, see how they feel, and you'll quickly discover their strengths and weaknesses in practice.

What's your take? Have you tried building something with either REST or GraphQL? Please share your experience.

I would appreciate any feedback you could provide, as this is my first article.