public-api-docs

Technical considerations

Rate Limiting

We are using AWS Web Application Firewall to protect our platform, against Denial-of-service attacks, by implementing rate limit rules.

The general rate limit is aggregated by Source IP address with a limit of 3,000 requests / 5 minutes. Some endpoints, for example vehicle discovery and sign-in, have lower limits.

Rate-limit response

A request that exceeds a firewall rate limit is answered with:

• HTTP status 429 Too Many Requests
• a Retry-After header, in seconds
• a JSON body in the error response format:

{
  "errorCode": "RATE_LIMITED",
  "userMessage": "Too many requests. Please try again later.",
  "httpStatus": 429
}

The rate-limit response is returned by the firewall before the request reaches the API, so the body is always the same and contains no traceId.

When you receive it, stop or slow down the requests from that client and retry later with a backoff, waiting at least the Retry-After value. Retrying immediately keeps the rate above the limit and extends the block. See also the Fair use policy.

Some endpoints also answer 429 themselves, with their own error code and without the RATE_LIMITED body, for example AUTH227 on email sign-in. Handle these as the API reference of the endpoint describes.

How the limit is measured

AWS WAF rate limiting is designed to control high request rates and protect your application’s availability in the most efficient and effective way possible. It’s not intended for precise request-rate limiting.

• AWS WAF estimates the current request rate using an algorithm that gives more importance to more recent requests. Because of this, AWS WAF will apply rate limiting near the limit that you set, but does not guarantee an exact limit match.

• AWS WAF estimates the rate of requests about every 30 seconds, using requests for the prior 5 minutes each time. Due to this and other factors such as propagation delays, it’s possible for requests to be coming in at too high a rate for up to 30 seconds before AWS WAF detects and rate limits them. Similarly. the request rate can be below the limit for up to 30 seconds before AWS WAF detects the decrease and discontinues the rate limiting action. Usually, this delay is below 20 seconds. Request rate limiting from AWS docs.

Polling of resources

Most of our first-level entities like:

• Users
• Rentals
• Invoices
• Issues
• many more provide updatedAt field, which can be facilitated to implement polling to receive all updates to existing and all new instances of an entity.

Health checks

We provide a health check endpoint for our services, which can be used to monitor the health of our services.

It is currently a work in progress to provide a more detailed health check in the future, which will include the health of the database and the health of other subsystems.

Following an example on how the health endpoint can be invoked:

production http { "method": "GET", "url": "/health/ping", "baseUrl": "https://go.api.gourban.services/v1", }