How Should ROR Handle API Client Identification?

Since ROR’s launch in 2019, the ROR API has been provided at no cost and with no registration or credentials required. While requiring no registration or identification reduces barriers to entry, it makes managing the health and stability of the API challenging amid constant and growing use.

In recent months, “impolite” use of the ROR API has presented a particular challenge, which causes degraded performance for all API users. Examples of “impolite” use include:

• Sustained high levels of requests just below the rate limit from multiple coordinated IP addresses
• Use of proxies and frequent IP changing to evade rate-limiting

IP-based rate limiting, which ROR already has in place at a limit of 2,000 requests in every 5 minutes, is not an effective solution to the behaviors listed above. Additionally, monitoring and blocking impolite behavior based on IP address is not a scalable solution as ROR API use continues to grow. ROR is therefore seeking to implement a lightweight solution to allow monitoring and managing API traffic based on criteria other than IP address.

Goals

• Maintain stability and usability of ROR API by enabling throttling/blocking based on some sort of client identification rather than IP address

• Allow ROR team to better support users by enabling ROR team to contact users whose requests generate lots of errors, are incorrectly formatted, etc and provide them with assistance fixing their requests

• Allow ROR team more insight into API usage patterns than can be gathered from IP addresses alone, which help to guide technical decisions and architecture approaches

Scope

ROR is seeking feedback on the the following proposed change:

The potential addition of API client identification in order to receive a rate limit of 2000 requests per 5 minute period. Requests without identification will receive a lower rate limit of 50 requests per 5 minute period.

Any additional revisions to ROR’s API are out of scope for this proposal, but can be submitted for consideration to ROR’s roadmap.

Proposed changes

In keeping with ROR’s objective of maintaining low barriers to entry, two options for identifying API clients have been developed. Both approaches involve providing an additional URL parameter or request header with each API request. Neither of these approaches are intended to provide authentication or authorization, therefore values provided are not secret and can be passed and stored as plain text. Full details of the proposed changes, pros and cons, privacy considerations, examples, and implementation timing are available in the proposal draft.

Giving feedback

To give feedback, please visit the proposal document and suggest changes to the text or add comments in the margin by October 4th, 2024. Feedback about the “Questions to consider” noted in the document is particularly appreciated. We’ll give a summary of the responses and discuss implementation at the ROR Community Call in November.

Let us know what you think! We appreciate your time and all that you do to help us make ROR the best service it can be.