API Endpoint — Complete Guide to URL Design

In this tutorial, you will learn about API Endpoint. We cover key concepts, practical examples, and best practices to help you master this topic.

An API endpoint is a specific URL where an API receives requests, with well-defined HTTP methods, path parameters, query strings, and request/response bodies for each operation.

What You'll Learn

• Endpoint URL structure and components
• HTTP methods and their semantics
• Path vs query parameters

Why It Matters

Every API interaction starts at an endpoint. Well-designed endpoints are intuitive to discover and use; poorly designed ones cause confusion and integration errors.

Real-World Use

Durga Antivirus Pro threat API endpoints follow a consistent pattern: /api/v1/threats (list), /api/v1/threats/{id} (get), /api/v1/threats/{id}/scan (action). Each has one clear purpose.

flowchart LR
    U["Endpoint URL"] --> B["Base: /api/v1"]
    U --> R["Resource: /threats"]
    U --> P["Path Param: /{id}"]
    U --> A["Action: /scan"]
    U --> Q["Query: ?severity=high"]
    style U fill:#dbeafe,stroke:#2563eb

Code Examples

# Well-designed endpoints
GET    /api/v1/users              # List users
POST   /api/v1/users              # Create user
GET    /api/v1/users/{id}         # Get user
PUT    /api/v1/users/{id}         # Replace user
PATCH  /api/v1/users/{id}         # Update user partially
DELETE /api/v1/users/{id}         # Delete user

# Poorly designed endpoints
GET    /api/getUsers
POST   /api/createNewUser
GET    /api/user?id={id}
POST   /api/deleteUser

Expected output: Consistent CRUD endpoints are predictable; inconsistent ones require documentation for every endpoint.

// Express endpoint with path and query parameters
const express = require('express');
const app = express();

// Path parameter for resource ID
app.get('/api/v1/threats/:id', (req, res) => {
  const threatId = req.params.id;
  // Query parameters for filtering
  const includeDetails = req.query.details === 'true';
  const threat = findThreat(threatId);
  if (!threat) {
    return res.status(404).json({ error: 'Threat not found' });
  }
  res.json(includeDetails ? threat : { id: threat.id, name: threat.name });
});

// Collection endpoint with pagination
app.get('/api/v1/threats', (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 20;
  const threats = queryThreats(page, limit);
  res.json({
    data: threats,
    meta: { page, limit, total: countThreats() }
  });
});

Expected output: Path parameters identify resources; query parameters filter and paginate collections.

# Action endpoints for non-CRUD operations
from flask import Flask, request, jsonify

app = Flask(__name__)

# CRUD is the norm
@app.route('/api/v1/threats/<id>/scan', methods=['POST'])
def scan_threat(id):
    # Action endpoint for non-CRUD operations
    severity = request.json.get('severity', 'medium')
    result = perform_scan(id, severity)
    return jsonify({'scan_id': result.id, 'status': 'pending'}), 202

@app.route('/api/v1/threats/<id>/scan/<scan_id>', methods=['GET'])
def get_scan_result(id, scan_id):
    result = get_scan(scan_id)
    if not result:
        return jsonify({'error': 'Scan not found'}), 404
    return jsonify({'status': result.status, 'findings': result.findings})

Expected output: Action endpoints use POST with verb in the URL for operations that do not fit CRUD.

Common Mistakes

1. Verbs in URL

Using /api/getUsers instead of GET /api/users violates REST conventions and confuses developers.

2. Inconsistent Pluralization

Some endpoints plural (/users), others singular (/user). Pick one convention (plural) and use everywhere.

3. Deep Nesting

/api/users/{id}/orders/{id}/items/{id} is hard to navigate. Keep nesting to 2-3 levels max.

4. Overloading GET with Side Effects

GET requests should not modify state. A GET that creates a resource violates HTTP semantics.

5. No Response for Empty Collections

Empty collections should return [] with 200, not 404. A 404 means the collection does not exist.

Practice Questions

1. What are the components of an API endpoint URL?
2. Why should CRUD operations use HTTP methods instead of verbs in the URL?
3. What is the difference between path and query parameters?
4. When should you use action endpoints (POST with verb)?
5. Why should empty collections return [] with 200 instead of 404?

Answers:

1. Base URL, resource path, path parameters, query parameters.
2. HTTP methods (GET, POST, PUT, DELETE) Express the operation; verbs in the URL are redundant.
3. Path parameters identify specific resources; query parameters filter or modify the response.
4. For operations that are not CRUD (send email, scan file, approve request).
5. 404 means the resource does not exist; an empty collection exists but has no items.

Challenge: Redesign the following endpoints to follow RESTful conventions: /api/getProduct?id=5, /api/deleteProduct, /api/createProduct, /api/updateProductInfo.

FAQ

Mini Project

Design the full set of endpoints for a blog API (posts, comments, authors, tags) following RESTful conventions. Include: CRUD endpoints, action endpoints (publish, archive), proper pagination, and consistent error responses.

What's Next

Explore API design principles for designing intuitive endpoints, or learn about API contracts for formal endpoint specifications.