Api_design

Chapter 16: API Design Principles

Building Effective Application Programming Interfaces

---

16.1 What is an API?

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

    API Overview
    ===========

    Client                              Server
    +-------+                          +-------+
    |       |   HTTP Request           |       |
    |  App  | -----------------------> |  API  |
    |       |   HTTP Response          |       |
    |       | <----------------------- |       |
    +-------+                          +-------+

    Types of APIs:
    - REST (Representational State Transfer)
    - GraphQL
    - gRPC
    - WebSocket
    - Webhook

---

16.2 REST API Design

Resource-Oriented Design

    REST Resources
    ==============

    Instead of:                    Use:
    +------------------------+    +--------------------+
    | /getAllUsers           |    | GET /users         |
    | /getUserById/123      |    | GET /users/123     |
    | /createNewUser        |    | POST /users        |
    | /updateUser/123       |    | PUT /users/123     |
    | /deleteUser/123      |    | DELETE /users/123  |
    +------------------------+    +--------------------+

    Resource = Noun (user, order, product)
    HTTP Method = Verb (GET, POST, PUT, DELETE)

HTTP Methods

Method	Description	Idempotent
GET	Retrieve resource	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Partial update	No
DELETE	Remove resource	Yes

---

16.3 API Endpoints

Naming Conventions

    Good vs Bad Endpoints
    =====================

    Bad:                    Good:
    /getUsers              GET /users
    /userslist            GET /users
    /getUser/123          GET /users/123
    /createUser           POST /users
    /updateUser/123       PUT /users/123
    /deleteUser/123       DELETE /users/123

    Nested Resources:
    GET /users/123/orders        (User's orders)
    GET /users/123/orders/456   (Specific order)
    POST /users/123/orders      (Create order for user)

Status Codes

    HTTP Status Codes
    =================

    Success:
    +------------------------------------------+
    | 200 - OK              Success           |
    | 201 - Created         Resource created  |
    | 204 - No Content      Successful delete |
    +------------------------------------------+

    Client Errors:
    +------------------------------------------+
    | 400 - Bad Request    Invalid input      |
    | 401 - Unauthorized   Not authenticated |
    | 403 - Forbidden     Not authorized     |
    | 404 - Not Found     Resource missing   |
    | 429 - Too Many      Rate limit         |
    +------------------------------------------+

    Server Errors:
    +------------------------------------------+
    | 500 - Internal Server Error             |
    | 502 - Bad Gateway                        |
    | 503 - Service Unavailable               |
    +------------------------------------------+

---

16.4 API Versioning

Strategies

    API Versioning
    ==============

    1. URL Path (Most Common)
    +----------------------------------+
    | /api/v1/users                    |
    | /api/v2/users                   |
    +----------------------------------+

    2. Query Parameter
    +----------------------------------+
    | /api/users?version=2            |
    +----------------------------------+

    3. Header
    +----------------------------------+
    | GET /api/users                   |
    | Accept-Version: v2               |
    +----------------------------------+

    4. Content Negotiation
    +----------------------------------+
    | GET /api/users                   |
    | Accept: application/vnd.app.v2+json
    +----------------------------------+

---

16.5 Pagination

Common Approaches

    Offset-Based Pagination
    ======================

    GET /users?page=2&limit=10

    Response:
    {
      "data": [...],
      "pagination": {
        "page": 2,
        "limit": 10,
        "total": 100,
        "totalPages": 10
      }
    }

    Cursor-Based Pagination
    ======================

    GET /users?cursor=abc123

    Response:
    {
      "data": [...],
      "pagination": {
        "nextCursor": "def456",
        "hasMore": true
      }
    }

    Cursor = opaque pointer to last item
    Better for large datasets!

---

16.6 Error Handling

Error Response Format

    Standard Error Response
    =======================

    {
      "error": {
        "code": "INVALID_INPUT",
        "message": "Validation failed",
        "details": [
          {
            "field": "email",
            "message": "Invalid email format"
          },
          {
            "field": "age",
            "message": "Must be positive"
          }
        ],
        "requestId": "req-12345"
      }
    }

---

16.7 Filtering and Sorting

Query Parameters

    Filtering
    =========

    GET /users?status=active
    GET /users?role=admin&status=active
    GET /users?age_gte=18&age_lte=30

    Common Operators:
    _eq, _ne, _gt, _gte, _lt, _lte
    _in, _contains, _starts_with

    Sorting
    =======

    GET /users?sort=created_at
    GET /users?sort=-created_at  (descending)
    GET /users?sort=name,created_at

---

16.8 Best Practices

Design Guidelines

Practice	Description
Use nouns	/users not /getUsers
Plural resources	/users not /user
Versioning	/api/v1/…
HTTPS only	Always use TLS
Pagination	For all list endpoints
Filtering	Allow query params
Error handling	Consistent format
Documentation	OpenAPI/Swagger

---

Summary

Key API design concepts:

1. RESTful principles - Resources, HTTP methods, status codes
2. Consistent naming - Nouns, plural, hierarchical
3. Versioning - Plan for changes
4. Pagination - Handle large datasets
5. Error handling - Clear, consistent errors
6. Filtering/sorting - Flexible queries
7. Documentation - Use OpenAPI spec

---

Next: Chapter 17: REST vs GraphQL