Full-Stack Development Fundamentals

Chapter 12: API Concepts

12.1 What is an API?

API (Application Programming Interface) is a set of rules and protocols that allows different software applications to communicate with each other.

API Purpose:

• Enable communication between front-end and back-end
• Allow third-party integrations
• Provide access to data and functionality
• Standardize how applications interact

API Types:

• REST API: Most common, uses HTTP methods
• GraphQL: Query language for APIs
• SOAP: XML-based protocol (legacy)
• WebSocket: Real-time bidirectional communication

How APIs Work:

1. Client sends HTTP request to API endpoint
2. Server processes request
3. Server returns response (usually JSON)
4. Client processes response

API Example:

// Request
GET https://api.example.com/users/1

// Response
{
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
}

12.2 REST API Basics

REST (Representational State Transfer) is an architectural style for designing web services.

REST Principles:

• Stateless: Each request contains all information needed
• Resource-Based: URLs represent resources (/users, /products)
• HTTP Methods: Use standard HTTP verbs
• JSON Format: Data exchange in JSON format

HTTP Methods:

• GET: Retrieve data (read-only, safe)
• POST: Create new resources
• PUT: Update entire resource
• PATCH: Partially update resource
• DELETE: Remove resource

REST API Examples:

// Get all users
GET /api/users

// Get specific user
GET /api/users/1

// Create new user
POST /api/users
Body: {"name": "John", "email": "john@example.com"}

// Update user
PUT /api/users/1
Body: {"name": "Jane", "email": "jane@example.com"}

// Delete user
DELETE /api/users/1

HTTP Status Codes:

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request
• 401 Unauthorized: Authentication required
• 404 Not Found: Resource doesn't exist
• 500 Server Error: Server-side error

12.3 API Design Best Practices

Well-designed APIs are intuitive, consistent, and easy to use.

URL Design:

• Use nouns, not verbs (/users not /getUsers)
• Use plural nouns for collections (/users, /products)
• Use hierarchical structure (/users/1/orders)
• Keep URLs simple and readable

Response Format:

• Use JSON for data exchange
• Include consistent structure
• Provide error messages
• Include metadata when needed

Error Handling:

• Return appropriate status codes
• Provide clear error messages
• Include error details in response
• Handle validation errors

12.4 API Authentication

APIs often require authentication to protect resources.

Authentication Methods:

• API Keys: Simple key in header or query parameter
• Bearer Tokens (JWT): Token-based authentication
• OAuth 2.0: Third-party authentication
• Basic Auth: Username and password (less secure)

JWT Example:

// Request with token
GET /api/users
Headers: {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

// Server validates token and returns data