Building High‑Performance APIs: Design, Optimization, and Security Best Practices

1. API Is More Than Data Transfer

Many think API is just a data channel, but a good API also solves collaboration problems by defining clear contracts, preventing mismatched data exchanges.

Example: without a unified API, teams may use Excel, private integrations, leading to field changes without notification.

Key point: API is a set of rules that must be documented clearly.

2. Designing API Interfaces

Before coding, ask three questions:

What inputs does the API need? Example: order lookup requires an order number; missing order number should cause immediate failure.

What outputs should the API return? Example: order API returns order number, amount, status, creation time; fields must be fixed and not expose internal errors.

Which aspects must remain immutable? Example: order status can change from "pending" to "paid" or "canceled" but not reverse; response must be identical across all server instances.

Based on these answers, follow several design rules:

2.1 One Function Per API

Do not mix user creation, query, email sending in a single endpoint. A case where payment and logistics were combined caused a full refactor when logistics changed.

2.2 Clear Naming and Error Messages

Use simple names, e.g., getOrders instead of obscure abbreviations.

Provide explicit error messages, e.g., “Amount format error, please enter a number” rather than generic error codes.

2.3 Avoid Overlapping Functionality

Separate “modify whole order” from “modify single order item” to keep responsibilities clear. Organize paths by business module, e.g., /orders/1 and /orders/1/items/1.

3. Optimization Techniques

Performance matters as much as functionality.

3.1 Batch Calls Instead of Loops

Fetching 100 users one by one should be replaced with a single “batch get users” endpoint.

3.2 Sync Core Logic, Async Non‑Core Work

Core steps like inventory deduction and order number generation must be synchronous; notifications and points accrual can be asynchronous. In one project, moving email/SMS sending to async reduced response time from 800 ms to 150 ms.

3.3 Cache Frequently Accessed Data

Store read‑heavy, rarely changed data (e.g., product lists) in Redis; query latency drops from milliseconds to microseconds. Remember to invalidate or update the cache when data changes.

3.4 Compress Large Payloads

Enable Gzip for responses such as a list of 100 items; payload size can shrink by over 70 %, speeding transmission.

3.5 Pre‑compute Expensive Results

For operations like fraud checks that require multiple data lookups, compute and store the result ahead of time so the support staff sees it instantly.

3.6 Reuse Resources

Creating and destroying database connections or threads is costly; pre‑allocate a pool and reuse objects to cut overhead.

4. Security Measures

Insecure APIs can be exploited.

4.1 Enforce HTTPS

All internal and third‑party calls must use HTTPS to prevent man‑in‑the‑middle attacks.

4.2 Mask Sensitive Data

Do not store or transmit raw phone numbers, ID numbers, or passwords. Show only partial phone numbers and encrypt passwords.

4.3 Authenticate Requests

Issue a unique token after login; require it on subsequent calls and set an expiration (e.g., 2 hours).

4.4 Prevent Duplicate Submissions

Use unique request identifiers or state checks so a payment cannot be processed twice.

4.5 Rate Limiting

Limit each user to, for example, 100 calls per minute; exceeding the limit results in rejection. Without it, a flood of requests can crash the service.

5. API Maintenance

5.1 Keep Documentation in Sync

When code changes, update the API docs immediately; otherwise callers will be confused.

5.2 Log Key Information

Record request time, endpoint, parameters, trace ID, and error messages. Avoid noisy logs but never omit essential identifiers like user ID or order number.

5.3 Version Management

Never modify an existing interface in place. Add a version prefix, e.g., /v1/orders and /v2/orders, keeping the old version operational while clients migrate.

5.4 Periodically Remove Redundant APIs

Identify endpoints that are unused for months and delete them after confirming no dependencies.

A good API is not about complexity but about clear rules, solid performance, robust security, and low maintenance cost.