Subject: Re: API Rate Limits and HTTP Code [#255]

From: Mark Nottingham <[email-masked]>
Date: Thu, 10 Feb 2011 17:06:09 +1100

Back to the original question here; should 503's definition be modified to explicitly allow rate limiting?

Proposal -- add one paragraph:

The meaning of "overloaded" is defined by and specific to the server, and can be selective (e.g., too many requests from a particular user).

Thoughts?

On 30/01/2011, at 12:50 AM, Mark Nottingham wrote:

> That's the concern underlying my question; scoping metadata in HTTP headers -- especially existing ones -- is often an exercise in "I meant what I said, and I said what I meant." 
> 
> While it's fine for Bryce to document what he means for interested developers to figure out, it's less possible for automated, generic software (e.g., a robot, spider, cache) to understand what concepts of user identity and metadata scope he has in mind. And, that's the point of defining it as a standard. 
> 
> Furthermore, if we define a scope that's sufficiently precise to be good for Bryce, it's very likely that it won't be good for someone else who's minted a different API.
> 
> At this point I'd observe that HTTP doesn't disallow Retry-After on a 2xx response; only that it doesn't define what it means. As such, Bryce is free to define additional semantics for it (or if that is distasteful, another header) so that people who read his documentation will know what to do with it. However, as per above I don't see how we can explicitly allow it without falling into this trap (beyond perhaps having some general introductory text about what is and isn't permissible in cases like this).
> 
> Those are my thoughts at the moment; it's late here, so I'll stop there.
> 
> 
> On 30/01/2011, at 12:41 AM, Karl Dubost wrote:
> 
>> 
>> Le 29 janv. 2011 à 00:04, Mark Nottingham a écrit :
>>> It seems like you want the scope of the 503 on the Retry-After to be the entire server, correct? I.e., on a 200, its semantic is roughly "here's your answer, but don't ask me (the server) another question for n seconds."
>> 
>> 
>> Given the example below I would say for a group of URIs pattern more than the full server. you could set for sure api.example.com but if the server is done with a 
>> example.com/api
>> example.com/profile
>> or even
>> example.com/api2
>> 
>> And there are different limits based on your subscription levels: Premium for api and silver for api2.
>> 
>> 
>> Le 28 janv. 2011 à 14:19, Bryce Nesbitt a écrit :
>>> I'm talking about incremental retrieval of a large data set.  Each
>>> resource is new to the client, and will not be cacheable:
>>> 
>>> GET /oai2.cgi?token=Az123Z&offset=0&count=100&query='Obama'
>>> HTTP/1.1 200
>>> Retry-After: 10
>>> Cache-Control: no-store, no-cache, private
>>> 
>>> GET /oai2.cgi?token=Az123Z&offset=100&count=100
>>> HTTP/1.1 503 Excessive queries from this IP address.  Please respect
>>> the Retry-After header.
>>> Retry-After: 10
>>> Cache-Control: no-store, no-cache, private
>> 
>> 
>> 
>> 
>> 
>> -- 
>> Karl Dubost - http://dev.opera.com/
>> Developer Relations & Tools, Opera Software
>> 
> 
> --
> Mark Nottingham   http://www.mnot.net/
> 
> 
> 
> 

--
Mark Nottingham   http://www.mnot.net/

---

From: Karl Dubost <[email-masked]>
Date: Thu, 10 Feb 2011 15:02:48 -0500

> Proposal -- add one paragraph:

Putting the message in context
http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-12#section-8.5.4

CURRENT TEXT

    8.5.4.  503 Service Unavailable

   The server is currently unable to handle the request due
   to a temporary overloading or maintenance of the server.
   The implication is that this is a temporary condition
   which will be alleviated after some delay. If known, the
   length of the delay MAY be indicated in a Retry-After
   header field. If no Retry-After is given, the client
   SHOULD handle the response as it would for a 500
   response.

|  The meaning of "overloaded" is defined by and specific to
|  the server, and can be selective (e.g., too many requests
|  from a particular user).
   
        Note: The existence of the 503 status code does not
        imply that a server must use it when becoming
        overloaded. Some servers might wish to simply refuse
        the connection.

I would propose (but maybe too detailed for the group?).

PROPOSAL for the additional text

    The meaning of "overloaded" is defined by and specific to
    the server, and can be selective depending on the request
    URI and its associated headers. For example, it doesn't 
    necessary mean a server malfunction but can be a notification 
    to inform the client that the server is used in excess for a 
    specific service (e.g., too many requests from a particular 
    user for an API).

For date, I guess it is ok. As the server should be able to create a date.
http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-08#section-9.3
    
     2. If the response status code conveys a server error, e.g.
    500 (Internal Server Error) or 503 (Service Unavailable),
    and it is inconvenient or impossible to generate a valid
    Date.