I’m Mário Mabande
a Software Engineer MSc in Computer Science ML Enthusiast

GraphQL vs REST: When to Choose Each and Why It Matters

Introduction

GraphQL vs REST is one of the most common debates in modern API development — and by the end of this article, you will know exactly which one to choose.In our previous articles, we explored SOAP, REST, and even built a RESTful API with Python and Django REST Framework. As a result, we saw how REST replaced SOAP as the dominant style for web services. Its simplicity, statelessness, and use of standard HTTP methods made it the natural choice.

However, the story of APIs did not end with REST. In 2015, Facebook open-sourced a technology called GraphQL. Since then, one question keeps appearing in technical discussions and architecture meetings: should I use REST or GraphQL?

In this article, we will go beyond the basics. First, we will understand why GraphQL was created and which problems REST could no longer solve. Then, we will compare how each approach works in depth. After that, we will look at famous public APIs that use each one. Finally, I will share the books you should read to master both technologies.

1. A Quick Recap: What is REST?

As defined in our previous article, REST (Representational State Transfer) is an architectural style for networked applications. Roy Fielding introduced it in his doctoral dissertation, “Architectural Styles and the Design of Network-based Software Architectures” (Fielding, 2000).

In short, REST defines a set of constraints to achieve performance, scalability, and simplicity:

• Client-Server: separation between user interface and data storage;
• Stateless: each request contains all the information needed to process it;
• Cacheable: responses must define themselves as cacheable or not;
• Uniform Interface: resources have URIs and use standard HTTP methods (GET, POST, PUT, PATCH, DELETE);
• Layered System: the architecture can be composed of hierarchical layers.

Since the 2000s, REST has been the industry standard. In fact, according to Postman’s State of the API Report, it remains the most used style among developers today (Postman, 2023).

So, if REST works so well, why did Facebook feel the need to create something new?

2. The Problem: Why REST Was No Longer Enough for Facebook

To understand GraphQL, we need to go back to 2012. At that time, Facebook was rebuilding its native mobile applications, and the context matters:

• Smartphones were becoming the main way people accessed the internet;
• Mobile networks (especially 3G) were slow and unreliable, above all in developing countries;
• Facebook’s data model was deeply interconnected: users have friends, friends have posts, posts have comments, and comments have authors.

Because of this context, the engineering team — led by Lee Byron, Nick Schrock, and Dan Schafer — faced three structural problems with REST (Byron, 2015).

2.1 Over-fetching

REST endpoints return a fixed data structure defined by the server. For example, when the mobile app requested GET /users/123, it received the complete user object: name, email, birthday, hometown, and work history. Yet the screen only needed the name and the profile picture. On slow networks, every wasted byte meant a slower experience. Moreover, it meant higher data costs for the user.

2.2 Under-fetching and the N+1 Requests Problem

The opposite problem also existed. To render the News Feed, the app needed data from several resources: the user, their posts, the comments, and the comment authors. Consequently, REST forced multiple sequential round trips:

GET /users/123          → get the user
GET /users/123/posts    → get their posts
GET /posts/1/comments   → get comments of post 1
GET /posts/2/comments   → get comments of post 2
...

Each round trip on a 3G network added latency. As a result, the app felt slow and users became frustrated.

2.3 Endpoint Proliferation and Versioning

To work around these limits, teams often created custom endpoints for specific screens, such as /users/123/newsfeed-mobile-v2. Over time, this produced dozens of endpoints that were hard to maintain and document. In addition, every design change in the app required backend changes and new API versions.

GraphQL was born as a direct answer to these three problems. It offers a single endpoint where the client — not the server — decides exactly which data it needs, in a single request.

3. What is GraphQL?

GraphQL is a query language for APIs and a server-side runtime that executes queries against a type system (GraphQL Foundation, 2024). Facebook developed it internally in 2012 and used it in production from 2013. Later, in 2015, the company open-sourced it. Today, the GraphQL Foundation, hosted by the Linux Foundation, governs the project.

One important clarification: GraphQL is not a database technology. It has no relation to graph databases like Neo4j. Instead, the “Graph” in the name refers to how it treats your data as a connected graph of objects.

Here is a simple analogy. Imagine ordering food at a restaurant:

• With REST, you order from a fixed menu. You ask for “Meal number 3” and receive everything in it — whether you wanted all of it or not.
• With GraphQL, you build your own plate. You tell the kitchen: “I want rice, chicken, and salad” — and that is exactly what you receive.

3.1 The Schema: The Contract Between Client and Server

Everything in GraphQL starts with the schema, written in the Schema Definition Language (SDL). The schema is strongly typed and works as a contract:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

The exclamation mark (!) means the field cannot be null. Thanks to this type system, we get powerful tooling: auto-completion, validation, and self-generated documentation.

3.2 Queries: Reading Data

A query is the equivalent of a GET in REST. However, the client specifies exactly which fields it wants:

query {
  user(id: "123") {
    name
    posts(limit: 3) {
      title
      comments(limit: 2) {
        text
        author {
          name
        }
      }
    }
  }
}

Notice what happened here. The entire News Feed problem from section 2.2 was solved in a single request. User, posts, comments, and authors — one round trip.

3.3 Mutations: Writing Data

Mutations create, update, or delete data. In other words, they are the equivalent of POST, PUT, PATCH, and DELETE:

mutation {
  createPost(title: "GraphQL vs REST", content: "...") {
    id
    title
  }
}

3.4 Subscriptions: Real-Time Data

Subscriptions let the client receive real-time updates from the server, usually via WebSockets:

subscription {
  newComment(postId: "1") {
    text
    author {
      name
    }
  }
}

3.5 Resolvers: Where the Logic Lives

On the server side, each field in the schema has a resolver — a function that fetches that specific piece of data. This is where GraphQL connects to your databases, microservices, or even existing REST APIs. In fact, a common migration strategy is to build a GraphQL layer on top of existing REST services.

4. GraphQL vs REST: In-Depth Comparison

Here is an honest observation. GraphQL solves the N+1 problem on the network side, between client and server. However, it can bring the same problem back on the server side, between the API and the database, if resolvers are written naively. For this reason, tools like DataLoader exist. Facebook created it to solve this issue through batching and caching (Facebook, 2015).

5. Famous Public APIs: Who Uses What?

Theory is important. Even so, seeing real-world adoption gives us a better perspective.

5.1 Famous Public REST APIs

• Stripe API — considered by many the gold standard of REST design. It offers predictable resources, consistent errors, and excellent documentation (Stripe, 2024). Therefore, if you want to learn REST design, study Stripe.
• Twilio API — communications (SMS, voice, WhatsApp) built entirely on RESTful conventions.
• GitHub REST API (v3) — one of the most used APIs in the world, available since 2011.
• Spotify Web API — music catalog, playlists, and player control via REST.
• OpenWeatherMap API — a classic for beginners learning to consume APIs.

5.2 Famous Public GraphQL APIs

• GitHub GraphQL API (v4) — the most emblematic case. In 2016, GitHub announced that its next-generation API would use GraphQL. The reasons were exactly the over-fetching and endpoint proliferation problems we discussed (GitHub, 2016). Interestingly, the same company still maintains both styles: v3 (REST) and v4 (GraphQL).
• Shopify Storefront & Admin APIs — Shopify adopted a GraphQL-first strategy for e-commerce. As a result, each storefront requests only the product data it needs (Shopify, 2024).
• The Rick and Morty API — a free GraphQL API with no authentication. It is perfect for study and practice.
• Countries API — another free GraphQL API, ideal for your first queries.
• AniList API — an anime and manga database, fully GraphQL.

Notice the pattern. Companies with complex, connected data and many client types (GitHub, Shopify, Facebook) gravitate towards GraphQL. On the other hand, companies with clear, transactional resources (Stripe, Twilio) remain successfully on REST.

6. When to Choose REST

Based on everything we analysed, REST remains the right choice when:

1. Your API is resource-oriented and CRUD-heavy. If your domain maps naturally to resources (tasks, users, products), REST’s simplicity is an advantage.
2. HTTP caching is critical. REST GET requests are cacheable by browsers, CDNs, and proxies. In contrast, this is very hard to replicate with GraphQL.
3. You are building a public API for third parties. REST’s universality lowers the entry barrier for external developers.
4. Your team is small or the deadline is short. There is no schema to design and no resolvers to write.
5. File uploads are a core feature. REST handles multipart/form-data natively.

7. When to Choose GraphQL

On the other hand, GraphQL becomes the better choice when its original problems are your problems:

1. Multiple clients with different data needs. For instance, a web app, a mobile app, and a smartwatch app consuming the same API — each requesting only what it needs.
2. Deeply interconnected data. If one screen needs data from 4 or 5 REST endpoints, GraphQL’s nested queries remove the extra round trips.
3. Mobile-first products on unreliable networks. This was Facebook’s original motivation. Furthermore, it is especially relevant in our African context, where mobile data is expensive and networks are inconsistent.
4. Fast-moving frontend teams. Frontend developers add fields to their queries without waiting for backend changes.
5. Real-time features in the same API. Subscriptions provide a standard model for live updates.

Finally, remember: the two are not mutually exclusive. A common architecture uses REST for authentication, webhooks, and uploads, while GraphQL handles complex data fetching. After all, GitHub itself maintains both.

8. Conclusion

GraphQL did not appear to “kill” REST. Instead, it appeared because Facebook’s reality in 2012 — mobile clients, slow networks, connected data — exposed real limits in the fixed-endpoint model: over-fetching, under-fetching, and endpoint proliferation.

REST remains an excellent choice. It is simple, cacheable, and universal, and it still powers most of the world’s APIs. Meanwhile, GraphQL is a specialized tool that shines when data complexity and client diversity justify its extra server-side cost.

Therefore, before choosing, ask yourself:

1. How interconnected is my data?
2. How many client types will consume this API?
3. How important is HTTP caching for my use case?
4. Can my team manage a GraphQL server responsibly (query complexity, N+1, security)?

The honest answer to these four questions will point you in the right direction.

Have you used GraphQL in production? Do you prefer REST? Share your experience in the comments — your feedback matters and helps make these articles better!

Thank you for reading!

9. Recommended Books

Before the formal reference list, here is my suggested reading order:

To study REST: start with Richardson and Ruby (2007), the classic that popularized REST; then move to Richardson et al. (2013), its modernized successor; and keep Massé (2011) as a practical design rulebook. For the theoretical foundation, read Fielding’s (2000) original dissertation.

To study GraphQL: start with Porcello and Banks (2018), the best entry point for beginners; then Wieruch (2018) for a practical, project-based approach; and finish with Giroux (2020), written by a former GitHub engineer, to learn how to run GraphQL at scale in production.

10. References

Byron, L. (2015, September 14). GraphQL: A data query language. Engineering at Meta. https://engineering.fb.com/2015/09/14/core-infra/graphql-a-data-query-language/

Facebook. (2015). DataLoader [Computer software]. GitHub. https://github.com/graphql/dataloader

Fielding, R. T. (2000). Architectural styles and the design of network-based software architectures [Doctoral dissertation, University of California, Irvine]. https://ics.uci.edu/~fielding/pubs/dissertation/top.htm

GitHub. (2016, September 14). The GitHub GraphQL API. The GitHub Blog. https://github.blog/2016-09-14-the-github-graphql-api/

Giroux, M.-A. (2020). Production ready GraphQL. Self-published. https://book.productionreadygraphql.com/

GraphQL Foundation. (2024). GraphQL documentation. https://graphql.org/

Massé, M. (2011). REST API design rulebook. O’Reilly Media.

Porcello, E., & Banks, A. (2018). Learning GraphQL: Declarative data fetching for modern web apps. O’Reilly Media.

Postman. (2023). 2023 state of the API report. https://www.postman.com/state-of-api/

Richardson, L., Amundsen, M., & Ruby, S. (2013). RESTful web APIs: Services for a changing world. O’Reilly Media.

Richardson, L., & Ruby, S. (2007). RESTful web services. O’Reilly Media.

Shopify. (2024). Shopify API documentation. Shopify.dev. https://shopify.dev/docs/api

Stripe. (2024). Stripe API reference. https://stripe.com/docs/api

Wieruch, R. (2018). The road to GraphQL. Self-published. https://www.robinwieruch.de/the-road-to-graphql-book/

How to Protect Your WordPress Site: Essential Security Step-by-Step

Introduction

A website is the digital business card of any business or individual. To help protect this asset, this WordPress security guide was created to present best practices based on industry reports, ensuring visitors feel safe and data remains protected.

For this experience to be positive, it is essential that visitors feel safe — especially when the website is used for contact forms, user authentication, or e-commerce transactions. However, many basic security aspects are still neglected, leaving numerous websites vulnerable to attacks.

This article presents WordPress security best practices, based on reports and studies from recognised organisations in the field of cybersecurity.

1. Why focus on WordPress?

WordPress is currently the most widely used Content Management System (CMS) in the world, driven by its flexibility, large community, and extensive ecosystem of plugins and themes. However, this popularity also makes it one of the main targets of automated attacks (Wordfence, 2023).

It is important to note that the WordPress core itself is considered secure and is continuously audited by experts. Most security incidents are related to third-party plugins, themes, and poor maintenance practices (WPScan, 2024).

2. The first critical step: choosing themes and plugins

WordPress website security begins even before the site is published, during the selection of components to be installed.

2.1 Official and trusted sources

This is the golden rule. Installing a plugin or theme from untrusted sources is equivalent to granting administrative privileges to an unknown person. It is recommended to obtain themes and plugins only from recognised sources, such as:

• The official WordPress directory (WordPress.org)
• Reputable premium theme marketplaces (e.g., ThemeForest, Elegant Themes, StudioPress)

According to the WordPress Foundation (2024), the official directory undergoes continuous review processes, significantly reducing the risk of malicious code.

2.2 The risk of “nulled” themes

Finding a paid premium plugin available “for free” on unofficial websites is a major red flag. These themes and plugins, known as nulled (pirated versions), represent one of the greatest security risks, as they often contain:

• Backdoors
• Malicious scripts
• Code for spam distribution or traffic redirection

In addition, users lose access to critical security updates, leaving the website exposed to already known vulnerabilities (Kaspersky, 2023).

3. The reality of attacks: what the numbers say

The importance of WordPress security is supported by concrete data:

• More than 2,800 attacks per second target WordPress websites worldwide, mostly carried out by automated bots (HubSpot, 2023).
• Vulnerability reports indicate that over 95% of security flaws are related to plugins and themes, not the WordPress core itself (WPScan, 2024).
• According to Sucuri, more than 50% of infected WordPress websites were outdated at the time of the attack (Sucuri, 2022).

These figures show that most attacks could be prevented by adopting basic maintenance best practices.

4. Main causes of WordPress website compromise

Based on reports from specialised web security companies, the most common causes of successful attacks include:

• Outdated plugins and themes containing known vulnerabilities;
• Weak passwords and the absence of two-factor authentication (2FA), facilitating brute-force attacks;
• Vulnerabilities in popular plugins, widely exploited due to their high number of installations (Wordfence, 2023; Kaspersky, 2023).

5. Recommended plugins

6. Essential protection measures

• Install only strictly necessary plugins and themes, avoiding excess;
• Remove inactive or unused plugins, even if they are disabled;
• Keep plugins, themes, and WordPress itself always up to date;
• Change the default login URL to reduce automated brute-force attacks;
• Limit the number of login attempts;
• Use two-factor authentication (2FA);
• Use services such as Cloudflare for firewall protection, bot mitigation, and SSL/TLS encryption (Cloudflare, 2024);
• Perform regular backups and store them outside the main server;
• Monitor logs and access reports to detect suspicious activity early.

7. Conclusion

WordPress security is not a one-time task, but a continuous process. Adopting practices such as regular updates, trusted sources, strong authentication, and external protection services significantly reduces the risk of security incidents.

Investing in digital security is a direct investment in a website’s credibility, availability, and trust.

8. References

Cloudflare. (2024). Cloudflare security overview. https://www.cloudflare.com

HubSpot. (2023). WordPress security issues and statistics. https://blog.hubspot.com

Kaspersky. (2023). Vulnerable WordPress plugins and themes. https://www.kaspersky.com

Sucuri. (2022). Website threat research report. https://sucuri.net

Wordfence. (2023). WordPress security report. https://www.wordfence.com

WPScan. (2024). WordPress vulnerability database. https://wpscan.com

WordPress Foundation. (2024). WordPress security. https://wordpress.org/about/security/

What are ADRs (Architecture Decision Records) and Why are They Important?

1. How I First Encountered ADRs

The first time I came across the term ADRs (Architecture Decision Records) was not during a training session or while reading a blog post — it was while working on a production system that had been running for some time. My role was to keep the system healthy and evolving: applying updates, writing tests, fixing bugs, and implementing small changes requested by the business team.

One day, the commercial department asked for what seemed like a simple change in one of the reports. It was a small modification, but the report was managed by a specific team that had authorization to request alterations. As usual, I prepared the change request by email: I described what needed to be changed, how it should work, and sent it to the senior developer responsible for that part of the system.

That’s how we handled changes at the time — every request and decision lived in emails.
But as the system grew, so did the complexity. Then one day, the senior developer replied and asked me to “write an ADR” for the change instead. I had no idea what that meant. He shared a few links and suggested I study what ADRs were — and then write my first one.

That request completely changed the way I think about software architecture.

2. The Problem With Email-Driven Decisions

At first, I didn’t understand why ADRs were necessary. Writing an email seemed enough — after all, it worked for small changes. But as the system grew larger and more complex, the cracks in that approach became obvious:

• 📬 Emails got lost — after months, we couldn’t remember which email explained why a particular decision was made.
• 🧭 No traceability — future developers (or even ourselves) had no way to understand the historical context behind past decisions.
• 🔁 Repetition and confusion — without a documented history, we often discussed the same decisions multiple times.
• ❌ Lack of accountability — it wasn’t always clear who approved a change or why a certain path was chosen.

This is known as the “Email-Driven Development” anti-pattern — relying on informal communication for critical decisions. It may feel fast and flexible, but it leads to serious long-term issues: poor visibility, loss of context, inconsistent implementation, and uncontrolled technical debt.

The solution to that problem was ADRs.

3. What ADRs Really Are

ADRs (Architecture Decision Records) are lightweight documents that record important architectural decisions made during the lifetime of a software project — including what was decided and, most importantly, why.

Think of an ADR as a technical diary for your system. Each record captures one significant decision and its full context: the problem it solves, the alternatives considered, the trade-offs involved, and the implications for the future.

For example, an ADR might describe:

• Why you chose a specific database technology
• Why you changed an API structure
• Why you adopted a new design pattern
• Why you introduced a new authentication mechanism

By documenting this knowledge, you create a living history of your architecture — something future engineers can learn from and build upon.

4. Why ADRs Are a Game-Changer

Over time, I wrote many ADRs. I realized that ADRs are not just about documentation — they’re a strategic tool that transforms how a team builds software.

Here’s why they matter:

• 🧠 They preserve knowledge: ADRs turn individual, informal knowledge into structured, shared knowledge.
• 📚 They explain the “why”: They provide the reasoning behind each choice, not just the decision itself.
• 🚀 They accelerate onboarding: New team members can quickly understand the project’s evolution and avoid repeating past mistakes.
• 🤝 They align the team: Everyone shares the same understanding of trade-offs, constraints, and design principles.
• 🔄 They support system evolution: Knowing why a decision was made helps future developers evolve the system safely and intelligently.

In short, ADRs act like a map — one that keeps the project from losing its direction over time.

5. The Structure of an ADR

There’s no universal format for ADRs, but most follow a simple, effective structure:

• Title: A clear description of the decision.
• Status: Proposed, Accepted, Superseded, or Deprecated.
• Context: The problem or need that led to the decision.
• Decision: The solution chosen.
• Consequences: The impacts (positive and negative).
• Alternatives: Other options considered and why they were rejected.

Example: Adopting PostgreSQL as a Primary Database

Here’s an example of a simple ADR that was eventually accepted:

# ADR 001: Adoption of PostgreSQL as Primary Database

**Date:** 2025-SEPT-15  
**Status:** Accepted  
**Deciders:** Architecture Team  
**Participants:** Backend Team  

## Context and Problem Statement
We needed a robust relational database that could support advanced JSON operations and maintain high levels of concurrency and data integrity as the system scaled horizontally.

## Decision
Adopt PostgreSQL version 16 as the project’s primary database system.

## Detailed Rationale
The decision was made based on several key technical requirements:

- Native JSONB support for efficient storage and querying of JSON documents.
- Advanced concurrency and data consistency features (ACID compliance) essential for transactional integrity.
- Strong community support and a clear development roadmap, ensuring long-term viability.
- Full compatibility with our existing ORM tools and application stack.

## Consequences and Implications

**Positive Impacts:**

- Superior performance in complex queries involving joins and aggregations.
- Greater flexibility in the data model due to native JSONB, allowing faster iteration.
- Strong security features and robust backup capabilities.

**Risks and Negative Impacts:**

- Learning curve for team members previously familiar only with MySQL.
- Requires additional monitoring for performance tuning and advanced configuration (e.g., connection pooling).

## Alternatives Considered

### MySQL 8.0
- **Advantages:** Team familiarity, widespread market adoption.  
- **Disadvantages:** Limited native JSON support compared to JSONB, weaker performance on complex queries.  
- **Reason for rejection:** Technical limitations for the project’s specific data modeling and querying use cases.

### MongoDB
- **Advantages:** Excellent performance with JSON documents, high scalability for non-relational data.  
- **Disadvantages:** Lack of robust ACID transactions, non-relational model fundamentally incompatible with core project data requirements.  
- **Reason for rejection:** Incompatibility with the relational nature of the project's most critical data structures.

6. Best Practices I Learned Along the Way

After writing ADRs regularly, I discovered several practices that make them far more effective:

When to Use (and When Not to Use) ADRs

ADRs should not be used for everything. Use them only to document decisions with significant and long-term impact on the architecture.

Workflow Practices:

1. ✍️ One decision per ADR: Keep it focused and easy to understand.
2. 📁 Organize them well: Store them in a dedicated folder, like /docs/adr/.
3. 🔁 Track status changes: Update the status when a decision evolves or is replaced.
4. 👥 Review as a team: ADRs should be discussed and approved collectively.
5. 🧰 Integrate them into your workflow: Include ADR reviews in pull requests or technical discussions.

Recommended Tools:

1. 🛠️ adr-tools: CLI for creating and managing ADRs.
2. 📂 GitHub/GitLab: Store ADRs as Markdown files and version them with code.
3. 🧑‍💻 Docs-as-Code: Treat your ADRs as part of your repository, not separate documentation.

7. Final Thoughts

Writing ADRs has changed how I approach software architecture. They taught me discipline: to think critically, evaluate alternatives carefully, and communicate decisions clearly.

They also gave me peace of mind: knowing that every major architectural decision is documented, justified, and traceable.

ADRs are far more than documentation — they’re a way to capture the architectural soul of a system. If you haven’t adopted ADRs yet, I encourage you to start today.

8. Next Steps

Please note that I am still early in my journey of mastering architectural documentation, and this article serves as a basic guide to getting started with ADRs.

To deepen your understanding and explore every aspect of this topic, I strongly recommend you use the references below. For the most comprehensive overview, read them in the following sequence:

References:

1. Documenting Architecture Decisions – Michael Nygard (The foundational work on the topic)
2. Basics of Architecture Decision Records (ADR)
3. 4 Best Practices for Creating Architecture Decision Records
4. Master Architecture Decision Records (ADRs): Best Practices for Effective Decision-Making
5. adr-tools – ADR CLI Tool (Practical implementation tool)
6. Awesome ADR – Community Resources
7. PostgreSQL Documentation (For the example context)