What is RESTful API Architecture?

REST stands for Representational State Transfer.

It’s a way for computers to talk to each other over the internet, usually between a frontend (like a website or app) and a backend (like a server or database).

A good way to think about it is a set of rules, “If you want to get, create, update, or delete something on a backend system, here’s how you should ask for it.”.

Those “somethings” are called resources — like users, products, posts, or orders.

Example:

A common example is an API for an E-commerce website.

Let's imagine we are creating an online shoe shop.

Our backend database will store information about the shoes we sell. We could create a REST API that works something like this:

An example URL could look something like this:

GET https://api.myshoeshop.com/shoes/123

With an example response:

{
    "id": 123,
    "name": "Running Shoes",
    "size": 10,
    "colour": "black"
}

Key Traits of REST APIs

• Stateless: Each request stands on its own, the server doesn’t “remember” previous requests.
• Resource-based: Everything is treated as a thing (user, post, comment, etc.).
• Uses HTTP: It relies on familiar web operations like GET, POST, PUT, and DELETE.
• Returns data (often JSON) that apps can easily understand.

REST Alternatives

Listed below are some alternatives to the REST API architecture.

GraphQL

GraphQL is a query language for APIs that Facebook created.

It lets a client, like a web or mobile app, ask for exactly the data it needs.

Unlike REST, where you get a fixed response from each endpoint, GraphQL lets you customise the shape of the data in a single request.

For example using REST:

GET https://api.myshoeshop.com/shoes/123

May return all the information about a shoe:

{
    "id": 123,
    "name": "Running Shoes",
    "size": 10,
    "colour": "black",
    "stock" : 100,
    "discount": "10%"  
}

However, with GraphQL we could just get the ID and name from the shoe

{
  shoe(id: 123) {
    id
    name
  }
}

Specific data returned:

{
  "data": {
    "shoe": {
      "id": "123",
      "name": "Running Shoes"
    }
  }
}

GraphQL can be useful if your client needs different data combinations from the same resources or if you want to minimise data transfer.

Pros:

• Flexible: the client controls what data it gets.
• Efficient: no over-fetching or under-fetching.
• Great developer tooling (like GraphiQL for testing queries).

Cons:

• More complex setup.
• Harder to cache responses.
• Can be overkill for simple APIs.

gRPC

gRPC stands for Google Remote Procedure Call. It is an efficient, high-performance communication protocol that uses binary data (Protocol Buffers) instead of JSON or XML.

It’s designed for service-to-service communication such as microservices talking to each other inside a backend system.

You define services using .proto files. Then both the client and server generate code from these files to communicate efficiently.

gRPC can be used when:

• Creating internal APIs between microservices.
• Systems need speed and efficiency (e.g. IoT devices, backend clusters).
• When you control both the client and the server.

Pros:

• Rapid and compact (uses binary data).
• Strong typing via .proto definitions.
• Supports streaming (send and receive continuously).

Cons:

• Harder to debug (binary data isn’t human-readable).
• Not ideal for browser clients (needs special adapters).
• Requires both sides to share .proto definitions.

WebSockets

WebSockets let the client and server keep an open two-way connection to communicate between.
Unlike REST or GraphQL (where the client must ask each time), WebSockets allow real-time updates allowing the server to send new data to the client the moment something changes.

WebSockets are often used when:

• Creating real-time apps: chat, gaming, dashboards, live notifications.
• Situations arise where data updates frequently and the data needs to appear immediately.

Pros:

• Real-time communication.
• Reduces repeated requests.
• Efficient for high-frequency updates.

Cons:

• More complex to scale and maintain connections.
• Doesn’t work well with caching.
• Harder to debug and secure at scale.

SOAP

SOAP or Simple Object Access Protocol is an older XML-based protocol for APIs.
It defines strict rules about message structure and relies on XML envelopes.
It’s often used in enterprise or legacy systems such as banking, insurance, or government software.

It's mainly used when:

• Large organisations or systems require strict security and reliability.
• There are integrations with older enterprise software (e.g. SAP, Oracle).
• When transaction integrity and formal contracts (WSDL) are important.

Pros:

• Built-in standards for security (WS-Security) and transactions.
• Strong typing and automatic documentation.
• very reliable for enterprise-level systems.

Cons:

• Very verbose (XML-heavy).
• Harder to read and slower than JSON.
• Not suited for modern web or mobile apps.

Build a RESFful API

This was a guide to what a REST API is, how it's used and some alternatives to REST.

If you're interested in building your own REST API with Java/Spring, see: Build your first REST API with Spring Boot and Java