Modern API Architecture: The Complete Guide to REST, GraphQL, and gRPC

1// Well-structured REST API example with Express.js
2import express from 'express';
3import { z } from 'zod';
4
5const app = express();
6
7const ProductSchema = z.object({
8  name: z.string().min(1).max(200),
9  price: z.number().positive(),
10  category: z.enum(['electronics', 'clothing', 'food']),
11  inStock: z.boolean().default(true),
12});
13
14// GET /api/products — Paginated list
15app.get('/api/products', async (req, res) => {
16  const page = parseInt(req.query.page as string) || 1;
17  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
18  
19  const products = await db.products.findMany({
20    skip: (page - 1) * limit,
21    take: limit,
22    orderBy: { createdAt: 'desc' },
23  });
24
25  res.json({
26    data: products,
27    meta: { page, limit, total: await db.products.count() },
28    links: {
29      next: `/api/products?page=${page + 1}&limit=${limit}`,
30      prev: page > 1 ? `/api/products?page=${page - 1}&limit=${limit}` : null,
31    },
32  });
33});
34
35// POST /api/products — Creation with validation
36app.post('/api/products', async (req, res) => {
37  const result = ProductSchema.safeParse(req.body);
38  if (!result.success) {
39    return res.status(422).json({ errors: result.error.flatten() });
40  }
41  const product = await db.products.create({ data: result.data });
42  res.status(201).json({ data: product });
43});

1# GraphQL schema with relations and resolvers
2type Product {
3  id: ID!
4  name: String!
5  price: Float!
6  category: Category!
7  reviews(first: Int = 5, rating: Int): [Review!]!
8  relatedProducts(limit: Int = 3): [Product!]!
9}
10
11type Category {
12  id: ID!
13  name: String!
14  productCount: Int!
15}
16
17type Review {
18  id: ID!
19  author: User!
20  rating: Int!
21  comment: String
22  createdAt: DateTime!
23}
24
25type Query {
26  product(id: ID!): Product
27  products(
28    filter: ProductFilter
29    sort: ProductSort
30    pagination: PaginationInput
31  ): ProductConnection!
32}
33
34input ProductFilter {
35  category: String
36  minPrice: Float
37  maxPrice: Float
38  inStock: Boolean
39}
40
41# A single query replaces 3 REST calls
42query DashboardData {
43  featuredProducts: products(filter: { inStock: true }, sort: { field: POPULARITY, order: DESC }, pagination: { first: 5 }) {
44    edges {
45      node {
46        name
47        price
48        category { name }
49        reviews(first: 1, rating: 5) { comment }
50      }
51    }
52  }
53}

1// gRPC service definition with Protocol Buffers
2syntax = "proto3";
3
4package ecommerce;
5
6service ProductService {
7  // Unary RPC
8  rpc GetProduct(GetProductRequest) returns (Product);
9  
10  // Server streaming — ideal for large lists
11  rpc ListProducts(ListProductsRequest) returns (stream Product);
12  
13  // Client streaming — data aggregation
14  rpc BatchCreateProducts(stream CreateProductRequest) returns (BatchResult);
15  
16  // Bidirectional streaming — real-time synchronization
17  rpc SyncInventory(stream InventoryUpdate) returns (stream InventoryStatus);
18}
19
20message Product {
21  string id = 1;
22  string name = 2;
23  double price = 3;
24  Category category = 4;
25  bool in_stock = 5;
26  repeated string tags = 6;
27  google.protobuf.Timestamp created_at = 7;
28}
29
30message GetProductRequest {
31  string id = 1;
32}
33
34message ListProductsRequest {
35  int32 page_size = 1;
36  string page_token = 2;
37  ProductFilter filter = 3;
38}
39
40message ProductFilter {
41  optional string category = 1;
42  optional double min_price = 2;
43  optional double max_price = 3;
44  optional bool in_stock = 4;
45}