API Design Guide: Creating Developer-Friendly APIs

 1# ✅ Good patterns
 2GET    /users                    # Get all users
 3GET    /users/123                # Get specific user
 4POST   /users                    # Create user
 5PUT    /users/123                # Update user
 6DELETE /users/123                # Delete user
 7
 8# ❌ Avoid these patterns
 9GET    /getAllUsers
10POST   /createUser
11PUT    /updateUser/123

 1// Success response
 2{
 3  "data": {
 4    "id": 123,
 5    "name": "John Doe"
 6  },
 7  "meta": {
 8    "timestamp": "2024-01-28T11:30:00Z"
 9  }
10}
11
12// Error response
13{
14  "error": {
15    "code": "VALIDATION_ERROR",
16    "message": "Invalid input data",
17    "details": [
18      { "field": "email", "message": "Email is required" }
19    ]
20  }
21}

 1# Filtering
 2GET /posts?status=published&author_id=123
 3
 4# Sorting
 5GET /posts?sort=-created_at
 6
 7# Pagination
 8GET /posts?page=2&per_page=20
 9
10# Field selection
11GET /posts?fields=id,title,author

 1// Express.js API endpoint
 2app.get('/posts', async (req, res) => {
 3  try {
 4    const {
 5      status,
 6      author_id,
 7      sort = 'created_at',
 8      page = 1,
 9      per_page = 20,
10    } = req.query;
11
12    let query = Post.query();
13
14    // Apply filters
15    if (status) query = query.where('status', status);
16    if (author_id) query = query.where('author_id', author_id);
17
18    // Apply sorting
19    const direction = sort.startsWith('-') ? 'desc' : 'asc';
20    const field = sort.replace(/^-/, '');
21    query = query.orderBy(field, direction);
22
23    // Apply pagination
24    const offset = (page - 1) * per_page;
25    query = query.offset(offset).limit(per_page);
26
27    const posts = await query;
28    const total = await Post.query().count();
29
30    res.json({
31      data: posts,
32      meta: {
33        total,
34        page: parseInt(page),
35        per_page: parseInt(per_page),
36        total_pages: Math.ceil(total / per_page),
37      },
38    });
39  } catch (error) {
40    res.status(500).json({
41      error: {
42        code: 'INTERNAL_ERROR',
43        message: 'An unexpected error occurred',
44      },
45    });
46  }
47});

 1// JWT middleware
 2const authenticateToken = (req, res, next) => {
 3  const token = req.headers.authorization?.split(' ')[1];
 4
 5  if (!token) {
 6    return res.status(401).json({
 7      error: {
 8        code: 'AUTHENTICATION_REQUIRED',
 9        message: 'Access token required',
10      },
11    });
12  }
13
14  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
15    if (err) {
16      return res.status(403).json({
17        error: {
18          code: 'INVALID_TOKEN',
19          message: 'Invalid token',
20        },
21      });
22    }
23
24    req.user = user;
25    next();
26  });
27};
28
29// Rate limiting
30const rateLimit = require('express-rate-limit');
31const limiter = rateLimit({
32  windowMs: 15 * 60 * 1000, // 15 minutes
33  max: 100, // limit each IP to 100 requests per windowMs
34});
35
36app.use('/api', limiter);

 1openapi: 3.0.3
 2info:
 3  title: Blog API
 4  version: 1.0.0
 5
 6paths:
 7  /posts:
 8    get:
 9      summary: Get posts
10      parameters:
11        - name: status
12          in: query
13          schema:
14            type: string
15            enum: [draft, published]
16      responses:
17        '200':
18          description: Success
19          content:
20            application/json:
21              schema:
22                type: object
23                properties:
24                  data:
25                    type: array
26                    items:
27                      $ref: '#/components/schemas/Post'