Express API Introduction

What is an Express API?

An Express API is a web service built using Express.js that allows different applications to communicate with each other over HTTP. Express.js makes it easy to create these APIs by providing a simple, flexible framework for handling HTTP requests and responses.

In today's interconnected world, APIs (Application Programming Interfaces) are the backbone of modern web applications. They enable different software systems to exchange data and functionality seamlessly.

Why Use Express for APIs?

Express.js has become one of the most popular choices for building APIs for several reasons:

• Lightweight & Minimal: Express doesn't come with unnecessary features, giving you the freedom to structure your API as needed.
• Flexible: It works with various middleware and can be integrated with different databases and libraries.
• Performance: Express is built on Node.js, which excels at handling many concurrent connections with minimal overhead.
• Large Community: As one of the most popular Node.js frameworks, Express has extensive documentation and community support.

Setting Up Your First Express API

Let's start by creating a simple Express API. First, make sure you have Node.js installed, then follow these steps:

1. Create a new project

bash

mkdir express-api-demo
cd express-api-demo
npm init -y

2. Install Express

bash

npm install express

3. Create your first API file

Create a file named app.js with the following content:

javascript

const express = require('express');
const app = express();
const port = 3000;

// Middleware to parse JSON requests
app.use(express.json());

// A simple GET endpoint
app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello, World!' });
});

// Start the server
app.listen(port, () => {
  console.log(`API server running at http://localhost:${port}`);
});

4. Run your API

bash

node app.js

Now you can access your API at http://localhost:3000/api/hello. If you visit this URL in your browser, you'll see:

json

{
  "message": "Hello, World!"
}

Understanding API Routes

Routes are one of the most important concepts in Express APIs. A route defines how your application responds to client requests to specific endpoints.

Basic Route Structure

javascript

app.METHOD(PATH, HANDLER);

Where:

• app is your Express application
• METHOD is an HTTP method (like GET, POST, PUT, DELETE)
• PATH is the path on the server
• HANDLER is the function executed when the route is matched

Example of Different HTTP Methods

Let's expand our API with different HTTP methods:

javascript

// GET request - Retrieve data
app.get('/api/users', (req, res) => {
  const users = [
    { id: 1, name: 'John' },
    { id: 2, name: 'Jane' }
  ];
  res.json(users);
});

// POST request - Create new data
app.post('/api/users', (req, res) => {
  // req.body contains the submitted data
  const newUser = req.body;
  
  // In a real app, you would save this to a database
  console.log('Created new user:', newUser);
  
  // Return the created user with a 201 (Created) status
  res.status(201).json({
    message: 'User created successfully',
    user: newUser
  });
});

// PUT request - Update existing data
app.put('/api/users/:id', (req, res) => {
  const userId = req.params.id;
  const updatedData = req.body;
  
  console.log(`Updating user ${userId} with:`, updatedData);
  
  res.json({
    message: `User ${userId} updated successfully`
  });
});

// DELETE request - Remove data
app.delete('/api/users/:id', (req, res) => {
  const userId = req.params.id;
  
  console.log(`Deleting user ${userId}`);
  
  res.json({
    message: `User ${userId} deleted successfully`
  });
});

Request and Response Objects

Express provides request and response objects that contain valuable information and methods.

Request Object

The request object represents the HTTP request and has properties for the request query string, parameters, body, HTTP headers, etc.

javascript

app.get('/api/items', (req, res) => {
  // URL query parameters: /api/items?category=electronics
  const category = req.query.category;
  
  // Route parameters: /api/items/:id
  // const id = req.params.id;
  
  // Request headers
  const userAgent = req.headers['user-agent'];
  
  // Request body (for POST/PUT requests)
  // const data = req.body;
  
  res.json({
    receivedQuery: { category },
    receivedHeader: { userAgent }
  });
});

Response Object

The response object represents the HTTP response that an Express app sends when it receives an HTTP request.

javascript

app.get('/api/examples/response', (req, res) => {
  // Setting status code
  res.status(200);
  
  // Sending JSON data
  // res.json({ name: 'John', age: 30 });
  
  // Setting headers
  res.set('Content-Type', 'application/json');
  
  // Chaining methods is common
  res.status(200).json({
    success: true,
    message: 'This shows different response methods'
  });
});

Building a Practical API

Let's create a more realistic API for managing a collection of books:

javascript

const express = require('express');
const app = express();
const port = 3000;

// Middleware
app.use(express.json());

// In-memory data store (in a real app, you'd use a database)
let books = [
  { id: 1, title: 'To Kill a Mockingbird', author: 'Harper Lee', year: 1960 },
  { id: 2, title: '1984', author: 'George Orwell', year: 1949 },
  { id: 3, title: 'The Great Gatsby', author: 'F. Scott Fitzgerald', year: 1925 }
];

// Route for getting all books
app.get('/api/books', (req, res) => {
  res.json(books);
});

// Route for getting a specific book
app.get('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id);
  const book = books.find(b => b.id === bookId);
  
  if (!book) {
    return res.status(404).json({ message: 'Book not found' });
  }
  
  res.json(book);
});

// Route for adding a new book
app.post('/api/books', (req, res) => {
  const { title, author, year } = req.body;
  
  // Validation
  if (!title || !author) {
    return res.status(400).json({ message: 'Title and author are required' });
  }
  
  // Create new book
  const newId = books.length > 0 ? Math.max(...books.map(b => b.id)) + 1 : 1;
  const newBook = {
    id: newId,
    title,
    author,
    year: year || null
  };
  
  // Add to collection
  books.push(newBook);
  
  // Return the created book
  res.status(201).json(newBook);
});

// Route for updating a book
app.put('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id);
  const bookIndex = books.findIndex(b => b.id === bookId);
  
  if (bookIndex === -1) {
    return res.status(404).json({ message: 'Book not found' });
  }
  
  // Update book with new data, keeping the same id
  books[bookIndex] = {
    ...books[bookIndex],
    ...req.body,
    id: bookId // Ensure ID doesn't change
  };
  
  res.json(books[bookIndex]);
});

// Route for deleting a book
app.delete('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id);
  const bookIndex = books.findIndex(b => b.id === bookId);
  
  if (bookIndex === -1) {
    return res.status(404).json({ message: 'Book not found' });
  }
  
  // Remove the book
  const deletedBook = books[bookIndex];
  books = books.filter(b => b.id !== bookId);
  
  res.json({ 
    message: 'Book deleted successfully', 
    deletedBook 
  });
});

// Start the server
app.listen(port, () => {
  console.log(`Book API server running at http://localhost:${port}`);
});

Testing Your API

You can test your API using tools like:

1. Browser - For simple GET requests
2. curl - For command-line testing
3. Postman - A popular API testing tool with GUI
4. Thunder Client - A Visual Studio Code extension for API testing

Example of testing with curl:

bash

# Get all books
curl http://localhost:3000/api/books

# Get a specific book
curl http://localhost:3000/api/books/1

# Add a new book
curl -X POST http://localhost:3000/api/books \
  -H "Content-Type: application/json" \
  -d '{"title":"The Hobbit","author":"J.R.R. Tolkien","year":1937}'

# Update a book
curl -X PUT http://localhost:3000/api/books/1 \
  -H "Content-Type: application/json" \
  -d '{"year":1961}'

# Delete a book
curl -X DELETE http://localhost:3000/api/books/2

Best Practices for Express APIs

1. Use appropriate HTTP methods

   • GET for retrieving data
   • POST for creating data
   • PUT/PATCH for updating data
   • DELETE for removing data

2. Use meaningful status codes

   • 200: OK
   • 201: Created
   • 400: Bad Request
   • 401: Unauthorized
   • 404: Not Found
   • 500: Internal Server Error

3. Structure your API routes

   • Use plural nouns for collections: /api/books not /api/book
   • Use resource IDs in URLs for specific resources: /api/books/123

4. Validate inputs

   • Always validate and sanitize request data
   • Return clear error messages

5. Implement error handling

   • Use try/catch blocks
   • Create middleware for centralized error handling

Summary

In this introduction to Express APIs, we've covered:

• Setting up a basic Express API server
• Creating routes with different HTTP methods
• Working with request and response objects
• Building a practical API for book management
• Testing API endpoints
• Best practices for API design

Express makes it easy to create robust APIs with minimal code, providing a solid foundation that can scale with your application's needs.

Additional Resources

• Express.js Official Documentation
• REST API Design Best Practices
• MDN HTTP Status Codes

Exercises

1. Extend the books API to add filtering by author or year
2. Add validation to ensure book titles are at least 3 characters long
3. Create a new API for a different resource (e.g., movies, products)
4. Implement pagination for the GET /api/books endpoint
5. Add sorting capabilities to the books API