REST API Introduction Explained — Beginner's Guide with Examples

REST (Representational State Transfer) is an architectural style for web APIs that uses standard HTTP methods to create scalable, stateless, and cacheable services.

What You’ll Learn

• The definition and origins of REST architecture
• The six constraints that define a RESTful system
• How HTTP methods map to CRUD operations
• Why REST became the dominant API design standard

Why RESTful APIs Matter

Before REST, web services relied on SOAP — a heavyweight XML-based protocol with steep learning curves and rigid contracts. REST simplified everything by using the web’s existing infrastructure: HTTP methods, URIs, and standard status codes. DodaTech’s Durga Antivirus Pro uses a RESTful API to let users query threat intelligence databases, submit suspicious files for analysis, and manage device security policies — all from a lightweight, cacheable interface.

    flowchart LR
    A["Web Services\n(SOAP, XML-RPC)"] --> B["REST\n(You are here)"]
    B --> C["RESTful Resources"]
    B --> D["RESTful Methods"]
    B --> E["GraphQL &\nModern APIs"]
    style B fill:#dbeafe,stroke:#2563eb
    style A fill:#fef3c7,stroke:#d97706
  

What is REST?

REST was defined by Roy Fielding in his 2000 PhD dissertation. He noticed that the web was already working well and wanted to formalize why it worked so that we could build better APIs. Think of REST as the building code for web APIs — it doesn’t tell you how to build your API, but it defines the rules that make it safe, scalable, and predictable.

Imagine you walk into a library. The shelves are organized (URIs), the librarian helps you find books (server), and you browse without rearranging the shelves (GET is safe). You can request a book from another library (POST), or return a book (PUT/PATCH). REST applies this same predictable interaction model to web services.

The Six REST Constraints

1. Client-Server Separation

The client (browser, mobile app) and server (API) are separate and evolve independently. Why? Imagine if changing your phone’s wallpaper required updating your bank’s servers. That would be chaos. Separation lets the frontend use React, Vue, or Swift while the backend uses Python, Go, or Java — they only need to agree on the API contract.

2. Statelessness

Each request from a client contains all the information the server needs. The server doesn’t store any session data between requests. Why? A stateless server can handle any request from any client without looking up prior history. This makes scaling easy — just add more servers behind a load balancer. No session synchronization needed.

A practical example: Durga Antivirus Pro sends a POST request to https://api.durga-antivirus.com/v1/scan with the file hash. The server checks its threat database and returns a result. The next request, even if sent to a different server instance, works exactly the same.

3. Cacheable

Responses must explicitly state whether they are cacheable or not. Why? Caching reduces server load and improves response times. When Durga Antivirus Pro clients request the latest virus definitions, the server returns a response with Cache-Control: public, max-age=3600, telling intermediate proxies and the client that this data is valid for one hour.

4. Uniform Interface

Resources are identified by URIs, manipulated through representations, and include enough information to describe how to process them. Why? Consistency means once you learn one REST API, you already understand most of another one. If /users returns a list of users and /users/123 returns a single user, then /products and /products/456 work the same way.

5. Layered System

The client cannot tell whether it’s communicating directly with the server or with an intermediary (load balancer, CDN, cache proxy). Why? Layers enable security (API gateways), performance (CDNs), and scalability (load balancers) without changing the client.

6. Code on Demand (Optional)

The server can send executable code (JavaScript, applets) to the client. This is the only optional constraint. It’s rarely used in modern APIs because executing server-provided code in a client raises security concerns.

REST and CRUD Operations

REST maps directly to database operations through HTTP methods:

This mapping is intuitive: you GET data like you get a book from a shelf, and you POST data like you post a letter — sending new information to be processed.

Common Mistakes

1. Thinking REST Is Just CRUD Over HTTP

REST is an architectural style, not just a way to expose database tables. Design resources around business concepts (orders, invoices, shipments) rather than database tables.

2. Ignoring the Uniform Interface

If your API uses different patterns for different resources (/getUser, /products/create), it’s not RESTful. Consistency across all endpoints is the defining feature of a RESTful API.

3. Treating REST as Always Better

REST excels for CRUD-heavy, cacheable APIs. But for complex, nested data requirements, GraphQL may be better. For formal enterprise contracts, SOAP may be better. Choose the right tool.

4. Mixing REST and RPC Styles

REST treats everything as a resource. RPC treats everything as a function call. Mixing /users (resource) with /calculateTax (action) confuses consumers. Be consistent.

5. Forgetting HTTP Status Codes

Returning 200 for everything and putting the status in the response body defeats the purpose of HTTP status codes. Use 201 for creation, 204 for deletion, 400 for bad requests.

Practice Questions

1. Who defined REST, and what was the original context?
2. What problem does the statelessness constraint solve?
3. Why is “Code on Demand” optional?
4. What is the difference between PUT and POST in REST?
5. How does the uniform interface improve developer experience?

Answers:

1. Roy Fielding in his 2000 PhD dissertation, analyzing what made the web work well.
2. Statelessness enables horizontal scaling — any server can handle any request without session state, so you can add servers behind a load balancer without synchronization.
3. It’s optional because executing server-provided code in clients raises security concerns and isn’t needed for most APIs.
4. POST creates a new resource (server assigns ID), while PUT updates or replaces an existing resource at a known URI. PUT is idempotent, POST is not.
5. Consistency reduces learning time — once a developer understands /users, they automatically understand /products, /orders, etc.

Challenge: In Durga Antivirus Pro, design REST endpoints for managing user-submitted threat reports. Include endpoints for creating, listing, updating, and deleting reports. Show the HTTP method, URI, and expected status code for each.

FAQ

Try It Yourself

Use curl to make real REST API calls from your terminal:

# GET request — fetch a post
curl https://jsonplaceholder.typicode.com/posts/1

# POST request — create a post
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"My Post","body":"Content here","userId":1}'

# DELETE request
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Each command returns JSON and a status code. Notice how the server responds differently to each method — that’s REST in action.

What’s Next

What’s Next

Congratulations on completing this Restful Introduction tutorial! Here’s where to go from here:

• Practice daily — Consistency is more important than long study sessions
• Build a project — Apply what you learned by building something real
• Explore related topics — Check out other tutorials in the same category
• Join the community — Discuss with other learners and share your progress

Remember: every expert was once a beginner. Keep coding!