Best Practices
Recommended patterns for building robust and performant integrations with STEF APIs.
Rate Limiting
Respect the rate limiting headers returned by the API:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of requests per window |
X-RateLimit-Remaining | Remaining requests in the current window |
X-RateLimit-Reset | Window reset timestamp |
Retry-After | Seconds to wait (if 429) |
Security
Secret Storage
Use environment variables or a secrets manager:
# .env
STEF_CLIENT_ID=your_client_id
STEF_CLIENT_SECRET=your_client_secret
# .gitignore
.env
Performance
Caching
- Cache responses from read endpoints that do not change frequently
- Respect the
Cache-ControlandETagheaders - Use conditional requests (
If-None-Match,If-Modified-Since)
Efficient Pagination
- Use the cursor-based pagination provided by the API
- Limit the number of items per page (
limit) to the strict minimum - Avoid loading all pages at once
Compression
Enable gzip compression in your requests:
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept-Encoding: gzip"
Monitoring
- Log response times and return codes
- Set up alerts on 4xx and 5xx errors
- Monitor your quota consumption via the portal dashboard