Understanding API Design: Basics, Rate Limiting, Version Management, Security, and Team Collaboration

When I first started web development in college, I followed free tutorials that taught me to build a shopping mall using only POST requests for every operation, which later turned out to be a convenience‑first but suboptimal approach.

In this article I discuss API concepts in a conversational style, dividing the content into five parts.

1. Introduction to APIs

Early tutorials often focus on server‑side rendering, where a URL like https://ajun24.com/user returns an entire HTML page. The missing piece is AJAX, which enables asynchronous JSON responses and separates front‑end from back‑end.

Understanding that APIs should follow REST conventions makes it clear what each endpoint does, e.g.:

GET /users                # retrieve user information
PATCH /users/{user_id}    # partially update a user

Consistent API naming is like using technical jargon in IT: once others see your endpoints they instantly know the provided service.

2. API Rate Limiting

Because of hardware and network limits, APIs cannot be called infinitely. Public cloud APIs often impose limits such as 30 calls per second per user.

Designing rate limiting starts with identifying the system bottleneck. If the API depends on a database or message queue, load‑testing can reveal the maximum sustainable request rate. For a monolithic deployment a simple token‑bucket algorithm suffices:

class TokenBucket(object):
    # rate: tokens added per second, capacity: max tokens
    def __init__(self, rate, capacity):
        self._rate = rate
        self._capacity = capacity
        self._current_amount = 0
        self._last_consume_time = int(time.time())

    def consume(self, token_amount):
        # calculate new tokens based on elapsed time
        increment = (int(time.time()) - self._last_consume_time) * self._rate
        self._current_amount = min(increment + self._current_amount, self._capacity)
        if token_amount > self._current_amount:
            return False
        self._last_consume_time = int(time.time())
        self._current_amount -= token_amount
        return True

In distributed environments the algorithm must be implemented at the proxy or API‑gateway layer rather than inside each service.

3. API Version Management

Just like software, APIs evolve. To avoid breaking existing clients, version numbers should be part of the URL, e.g. GET /api/v1/users and later GET /api/v2/users.

If a new endpoint is needed without a version, developers often create a different path (e.g., /get_user_info), which can lead to a confusing API surface.

4. API Permissions and Security

APIs exposed to the public must enforce authentication and authorization. Common approaches include IP whitelisting, token‑based authentication (OAuth, API keys), and user‑login checks.

Security also influences endpoint design; for example, exposing a raw user ID in GET /users/287435/orders can be risky, so a safer pattern is GET /users/me/orders.

5. Inter‑Team API Collaboration

When multiple teams need to consume each other's APIs, clear documentation, consistent naming, and agreed‑upon rate‑limiting policies become essential. The three guiding questions are: Can you understand the API? Will it survive heavy traffic? Is it protected against unauthorized use?

Although the topic is vast, summarizing these practical points helps developers build more maintainable and secure APIs.