Developer Guidelines

Best practices and guidelines for developing applications with the Fuel Finder API.

API rate limits for Information Recipients

Rate limiting is applied to the Fuel Finder Public API to ensure a high quality service is delivered for all users, and to protect client applications from unexpected loops.

You can make up to X requests within a 5 minute period. If you exceed this limit, you will receive a 429 Too Many Requests HTTP status code for each request made within the rest of the 5 minute time frame. At the end of the period, your rate limit will reset back to X requests.

If you have an application that requires a higher rate limit than this default, contact us.

We reserve the right to ban without notice applications that regularly exceed or attempt to bypass the rate limits.

Code Standards

Data Validation

Validate API responses before using the data:

• Check that required fields are present
• Validate data types and formats
• Handle null or undefined values gracefully
• Sanitize user inputs before making API requests

Performance Guidelines

Caching

Implement appropriate caching strategies:

• Station data: Cache for 1 hour (stations don't change frequently)
• Price data: Cache for 15 minutes (prices change more often)
• Search results: Cache for 5 minutes (balance between freshness and performance)
• Use HTTP caching headers when available
• Implement cache invalidation strategies

Request Optimization

Optimize your API requests for better performance:

• Use appropriate pagination to limit response sizes
• Request only the data fields you need
• Implement request batching where possible
• Use compression for large requests
• Avoid making unnecessary requests

Security Best Practices

OAuth 2.0 (client credentials) security

Warning Never expose client secrets or access tokens in clientside code or public repositories.

Secure handling practices:

• Store client secrets in environment variables or a secure secrets manager (not in source control).
• Use separate credentials per environment (test and production) and per application.
• Rotate client secrets regularly and immediately if you suspect compromise.
• Request the minimum scopes your integration needs (principle of least privilege).
• Keep access tokens shortlived; rely on issuing new tokens rather than reusing old ones.
• Do not log secrets or tokens; mask sensitive values in logs and error messages.
• Use HTTPS (TLS 1.2+) for all calls to the token endpoint and API endpoints.
• Monitor token usage for anomalies (unexpected IPs, spikes in requests) and revoke credentials if required.
• Protect servertoserver flows: run OAuth on backend services only; do not expose secrets to browsers or mobile apps

Input Sanitization

Always sanitize user inputs before making API requests:

• Validate data formats
• Sanitize search queries
• Escape special characters in URLs

User experience guidelines

Loading States

Provide clear feedback to users during API requests:

• Show loading indicators for API calls
• Display progress for long-running operations
• Provide estimated completion times when possible
• Allow users to cancel requests if appropriate

Error Handling

Always implement proper error handling in your applications:

• Check HTTP status codes before processing responses
• Handle network timeouts and connection errors
• Implement retry logic with exponential backoff
• Log errors appropriately for debugging

Present user-friendly error messages:

• Translate technical errors into user-friendly language
• Provide actionable suggestions when errors occur
• Offer alternative actions when possible
• Include contact information for support

Testing guidelines

Unit Testing

Write comprehensive unit tests for your API integration:

• Test all API endpoints you use
• Mock API responses for consistent testing
• Test error handling scenarios
• Validate data parsing and transformation
• Test authentication and authorization

Integration testing

Test your application with the API:

• Use the sandbox environment for testing
• Test with various data scenarios
• Verify rate limiting behavior
• Test network failure scenarios
• Validate performance under load

Monitoring and Logging

Application Monitoring

Implement monitoring for your API usage:

• Track API request success/failure rates
• Monitor response times and performance
• Alert on unusual usage patterns
• Track rate limit usage
• Monitor error rates and types

Logging best practices

Implement proper logging for debugging and monitoring:

• Log API requests and responses (without sensitive data)
• Include request IDs for tracing
• Log performance metrics
• Use appropriate log levels
• Implement log rotation and retention policies

Compliance and Legal

Terms of Service

Ensure compliance with our terms of service:

• Respect rate limits and usage quotas
• Don't attempt to circumvent security measures
• Use data responsibly and ethically
• Respect user privacy and data protection
• Follow applicable laws and regulations

Data Usage

Use API data appropriately:

• Don't redistribute raw API data
• Attribute data sources appropriately
• Respect intellectual property rights
• Don't use data for illegal or harmful purposes