 |
VOOZH | about |
|
VOOZH | about |
This document describes the API Integration Layer, which provides a centralized HTTP client for communicating with the SIMAP.ch REST API. The layer consists of the SimapClient class, endpoint definitions, and error handling mechanisms. This page focuses on the internal HTTP communication infrastructure used by all MCP tools, including rate limiting, URL building, and validation logic.
For information about the external SIMAP.ch API itself (versioning, data formats, limitations), see 5. SIMAP.ch API Integration For information about how tools are implemented and use this layer, see 3.2. Tool Architecture
The API Integration Layer is implemented in the src/api/ directory and consists of three main components:
| Component | File | Purpose |
|---|---|---|
| SimapClient | src/api/client.ts32-101 | HTTP client with request handling, timeout management, and schema validation. |
| SlidingWindowRateLimiter | src/api/rate-limiter.ts32-116 | FIFO queue-based rate limiter ensuring compliance with API limits. |
| Endpoint Constants | src/api/endpoints.ts5-31 | Centralized definitions of all SIMAP.ch API endpoints. |
Sources: src/api/client.ts1-137 src/api/rate-limiter.ts1-117 src/api/endpoints.ts1-32
The SimapClient class implements the core HTTP communication logic. It is typically used via the default singleton instance simap src/api/client.ts136 It leverages a SlidingWindowRateLimiter to manage request pacing and supports optional Zod schema validation for responses.
Diagram: SimapClient Internal Structure
Sources: src/api/client.ts32-42 src/api/client.ts23-27 src/api/client.ts136
The SlidingWindowRateLimiter src/api/rate-limiter.ts32-116 ensures that the client does not exceed the allowed request frequency. It uses a FIFO queue to serve concurrent callers in order src/api/rate-limiter.ts7-9
prune() method src/api/rate-limiter.ts75-81scheduleDrain() to "drain" the queue as soon as a slot becomes available src/api/rate-limiter.ts87-103 It uses timer.unref() to avoid keeping the Node.js event loop alive solely for rate limiting src/api/rate-limiter.ts102Sources: src/api/rate-limiter.ts27-30 src/api/rate-limiter.ts61-72 src/api/rate-limiter.ts87-103
The SimapClient.get<T>() method src/api/client.ts47-100 orchestrates the complete HTTP request lifecycle.
Diagram: Request Lifecycle
Sources: src/api/client.ts47-100 src/api/rate-limiter.ts61-72
All SIMAP.ch API endpoints are defined in the ENDPOINTS object src/api/endpoints.ts7-31 This centralizes path logic and provides helper functions for dynamic paths (e.g., those requiring a projectId).
The following diagram bridges the code identifiers in endpoints.ts to the conceptual entities and the tools that consume them.
Diagram: Code Entity to Tool Mapping
Sources: src/api/endpoints.ts7-31 src/api/client.ts136
The buildUrl function src/api/client.ts109-131 handles the assembly of the final request URL.
baseUrl trailing slash and endpoint leading slash do not result in double slashes src/api/client.ts115params record src/api/client.ts118
?key=v1&key=v2) using url.searchParams.append src/api/client.ts120-124Sources: src/api/client.ts109-131
When the API returns a non-OK status code, the client throws a SimapApiError src/api/client.ts72-78 This error includes the status code and the endpoint, allowing tool handlers to perform specific logic (such as mapping to user-friendly messages).
The client supports a verbose debug mode enabled via the SIMAP_MCP_DEBUG environment variable src/api/client.ts15-18
stderr src/api/client.ts57Buffer.byteLength), and request duration in milliseconds src/api/client.ts81-88Sources: src/api/client.ts15-18 src/api/client.ts54-58 src/api/client.ts81-91
The client enforces a 30-second timeout by default src/api/client.ts61 It uses an AbortController to signal the fetch call to terminate if the timeout is reached src/api/client.ts60-69 The timer is cleared in a finally block to prevent resource leaks src/api/client.ts97-99
Refresh this wiki