REST API Tutorial for Beginners

REST API Tutorial for Beginners

APIs power the modern internet. Every time you use a mobile app, check the weather, or make an online payment, you're interacting with APIs. Understanding APIs is essential for any developer, and REST is the most common API architecture.

This comprehensive tutorial explains REST APIs from scratch—what they are, how they work, and how to build and consume them.

What is an API?

Definition

API (Application Programming Interface) is a way for different software applications to communicate with each other. It defines the rules and protocols for how applications request and exchange data.

Real-World Analogy: Think of a restaurant:

• You (client) → make a request (order from menu)
• Waiter (API) → takes your request to the kitchen
• Kitchen (server) → prepares the food
• Waiter (API) → brings the response (food)

You don't need to know how the kitchen works—the waiter handles the communication.

Why APIs Matter

What is REST?

Definition

REST (Representational State Transfer) is an architectural style for designing networked applications. It's not a protocol or standard—it's a set of constraints and principles.

REST Principles

What is a RESTful API?

A RESTful API is an API that follows REST principles. It uses:

• Standard HTTP methods
• URLs to identify resources
• JSON or XML for data exchange
• HTTP status codes for response status

HTTP Fundamentals

HTTP Methods (Verbs)

REST APIs use HTTP methods to indicate the action:

CRUD Operations

HTTP Status Codes

Common Status Codes:

REST API Structure

URL Structure (Endpoints)

RESTful URLs are resource-based:

https://api.example.com/v1/users/123/orders

Breakdown:

• https:// - Protocol
• api.example.com - Domain
• /v1 - API version
• /users - Resource (collection)
• /123 - Resource ID (specific user)
• /orders - Sub-resource (user's orders)

Naming Conventions

Rules:

• Use nouns, not verbs
• Use plural names for collections
• Use lowercase
• Use hyphens for multi-word (if needed)

Request Structure

GET Request (Retrieve):

GET /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Accept: application/json

POST Request (Create):

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "John Doe",
    "email": "[email protected]",
    "age": 25
}

Response Structure

Success Response:

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "[email protected]",
    "age": 25,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response:

{
  "status": "error",
  "message": "User not found",
  "code": "USER_NOT_FOUND"
}

Data Formats

JSON (JavaScript Object Notation)

Most common format for REST APIs:

{
  "id": 1,
  "name": "John Doe",
  "email": "[email protected]",
  "roles": ["user", "admin"],
  "profile": {
    "bio": "Developer",
    "location": "India"
  },
  "active": true
}

JSON Data Types: | Type | Example | |------|---------| | String | "hello" | | Number | 42, 3.14 | | Boolean | true, false | | Null | null | | Array | [1, 2, 3] | | Object | {"key": "value"} |

Headers

Common HTTP headers:

Consuming REST APIs

Using JavaScript (Fetch)

GET Request:

fetch('https://api.example.com/users')
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error:', error));

With async/await:

async function getUsers() {
  try {
    const response = await fetch('https://api.example.com/users');
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
}

POST Request:

async function createUser(userData) {
  const response = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer token123',
    },
    body: JSON.stringify(userData),
  });
  return response.json();
}

// Usage
createUser({ name: 'John', email: '[email protected]' });

Using Python (Requests)

GET Request:

import requests

response = requests.get('https://api.example.com/users')
data = response.json()
print(data)

POST Request:

import requests

user_data = {
    'name': 'John',
    'email': '[email protected]'
}

response = requests.post(
    'https://api.example.com/users',
    json=user_data,
    headers={'Authorization': 'Bearer token123'}
)

print(response.status_code)
print(response.json())

Using cURL (Command Line)

GET:

curl https://api.example.com/users

POST:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "email": "[email protected]"}'

Building REST APIs

Example with Node.js (Express)

Setup:

npm init -y
npm install express

Basic API:

const express = require('express');
const app = express();
app.use(express.json());

// In-memory data store
let users = [
  { id: 1, name: 'John', email: '[email protected]' },
  { id: 2, name: 'Jane', email: '[email protected]' },
];

// GET all users
app.get('/api/users', (req, res) => {
  res.json(users);
});

// GET single user
app.get('/api/users/:id', (req, res) => {
  const user = users.find((u) => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ message: 'User not found' });
  }
  res.json(user);
});

// POST create user
app.post('/api/users', (req, res) => {
  const user = {
    id: users.length + 1,
    name: req.body.name,
    email: req.body.email,
  };
  users.push(user);
  res.status(201).json(user);
});

// PUT update user
app.put('/api/users/:id', (req, res) => {
  const user = users.find((u) => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ message: 'User not found' });
  }
  user.name = req.body.name;
  user.email = req.body.email;
  res.json(user);
});

// DELETE user
app.delete('/api/users/:id', (req, res) => {
  const index = users.findIndex((u) => u.id === parseInt(req.params.id));
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  users.splice(index, 1);
  res.status(204).send();
});

app.listen(3000, () => console.log('Server running on port 3000'));

Example with Python (Flask)

from flask import Flask, jsonify, request

app = Flask(__name__)

users = [
    {'id': 1, 'name': 'John', 'email': '[email protected]'},
    {'id': 2, 'name': 'Jane', 'email': '[email protected]'}
]

@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify(users)

@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    user = next((u for u in users if u['id'] == user_id), None)
    if not user:
        return jsonify({'message': 'User not found'}), 404
    return jsonify(user)

@app.route('/api/users', methods=['POST'])
def create_user():
    user = {
        'id': len(users) + 1,
        'name': request.json['name'],
        'email': request.json['email']
    }
    users.append(user)
    return jsonify(user), 201

if __name__ == '__main__':
    app.run(debug=True)

Authentication

Types of API Authentication

API Key Example

Request:

GET /api/data HTTP/1.1
X-API-Key: your-api-key-here

Bearer Token Example

Request:

GET /api/users HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT (JSON Web Token)

JWT is a self-contained token with three parts:

header.payload.signature

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4iLCJpYXQiOjE1MTYyMzkwMjJ9.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

API Design Best Practices

URL Design

Response Design

{
    "status": "success",
    "data": {
        "users": [...],
        "pagination": {
            "page": 1,
            "per_page": 20,
            "total": 100,
            "total_pages": 5
        }
    }
}

Error Handling

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Pagination

Query Parameters:

GET /api/users?page=2&per_page=20

Response:

{
    "data": [...],
    "pagination": {
        "page": 2,
        "per_page": 20,
        "total_items": 100,
        "total_pages": 5
    }
}

Filtering and Sorting

GET /api/products?category=electronics&price_min=1000&sort=price_desc

Testing APIs

Tools for Testing

Postman Usage

1. Create a new request
2. Select HTTP method (GET, POST, etc.)
3. Enter URL
4. Add headers (if needed)
5. Add body (for POST/PUT)
6. Click Send
7. View response

Automated Testing

JavaScript (Jest + Supertest):

const request = require('supertest');
const app = require('./app');

describe('Users API', () => {
  it('should get all users', async () => {
    const res = await request(app).get('/api/users');
    expect(res.statusCode).toBe(200);
    expect(res.body).toBeInstanceOf(Array);
  });

  it('should create a user', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ name: 'Test', email: '[email protected]' });
    expect(res.statusCode).toBe(201);
    expect(res.body.name).toBe('Test');
  });
});

Common API Examples to Explore

Public APIs for Practice

Key Takeaways

1. REST is an architecture—not a protocol
2. HTTP methods matter—GET, POST, PUT, DELETE
3. Status codes communicate—200s success, 400s client error, 500s server error
4. URLs are resource-based—use nouns, not verbs
5. JSON is standard—for request and response bodies
6. Authentication is essential—API keys, tokens, OAuth
7. Design for developers—clear, consistent, well-documented
8. Test your APIs—Postman, cURL, automated tests
9. Version your API—/v1, /v2 for backward compatibility
10. Practice with public APIs—before building your own

Frequently Asked Questions

What's the difference between REST and GraphQL?

REST uses multiple endpoints for different resources. GraphQL uses one endpoint where clients specify exactly what data they need. REST is simpler; GraphQL is more flexible for complex queries.

Is REST the same as HTTP?

No. REST is an architectural style, HTTP is a protocol. REST commonly uses HTTP, but REST principles could theoretically apply to other protocols.

How do I secure my REST API?

Use HTTPS, implement authentication (JWT/OAuth), validate inputs, rate limit requests, and use proper authorization for each endpoint.

What's the difference between PUT and PATCH?

PUT replaces the entire resource. PATCH updates only specified fields. Use PUT when updating everything, PATCH for partial updates.

How do I handle API versioning?

Common methods: URL path (/v1/users), header (Accept-Version: v1), or query param (?version=1). URL path is most common and visible.

Learning backend development? Explore more resources on Sproutern for programming tutorials, career guidance, and skill development.