What is REST API?

Definition

A REST API is a web service that follows REST (Representational State Transfer) architectural constraints, allowing systems to communicate over HTTP. REST was defined by Roy Fielding in his 2000 doctoral dissertation and has become the dominant approach for building web APIs.

RESTful APIs organize data into resources, each identified by a URL. Clients interact with these resources using standard HTTP methods: GET (read), POST (create), PUT/PATCH (update), and DELETE (remove).

Core Principles of REST

• Statelessness: Each request contains all information needed to process it. The server doesn't store client session state between requests.
• Resource-based: Everything is a resource identified by a URI (Uniform Resource Identifier). Resources are nouns, not verbs.
• HTTP methods: Standard HTTP verbs (GET, POST, PUT, PATCH, DELETE) map to CRUD operations.
• Representations: Resources can have multiple representations (JSON, XML, HTML). JSON is the most common format.
• HATEOAS: Hypermedia As The Engine Of Application State - responses include links to related resources.
• Uniform interface: A consistent, predictable interface for interacting with resources.

REST API Best Practices

Building well-designed REST APIs requires following established conventions:

• Use plural nouns for resource URLs: /users, /articles, not /getUser
• Use HTTP status codes correctly: 200 (OK), 201 (Created), 404 (Not Found), 422 (Validation Error)
• Version your APIs: /api/v1/users or via headers
• Support filtering, pagination, and sorting: /users?page=2&limit=10&sort=name
• Use consistent error response formats across all endpoints
• Implement proper authentication (JWT, OAuth)
• Document your API with OpenAPI/Swagger specifications

Code Example

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

items = {}

@app.get("/items/")          # List all items
async def list_items():
    return list(items.values())

@app.get("/items/{item_id}")  # Get single item
async def get_item(item_id: int):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return items[item_id]

@app.post("/items/", status_code=201)  # Create item
async def create_item(item: Item):
    item_id = len(items) + 1
    items[item_id] = item
    return {"id": item_id, **item.dict()}

Frequently Asked Questions

What is the difference between REST and RESTful?

REST is the architectural style defined by Roy Fielding. RESTful describes an API that follows REST constraints. In practice, most 'REST APIs' are technically 'RESTful' as they don't fully implement all REST constraints (like HATEOAS). The terms are often used interchangeably.

REST vs GraphQL - which is better?

Neither is universally better. REST is simpler, more cacheable, and better for resource-oriented APIs. GraphQL is better when clients need flexibility to request exactly the data they need, reducing over-fetching. Many production systems use both.