Improving specification goals

[ioggstream]

@darrelmiller suggests to review the specification goals.

While reviewing the goals for the draft I was wondering if they could be improved.

1. Standardizing the names and semantic of rate-limit headers;

2. Improve resiliency of HTTP infrastructures simplifying the enforcement and the adoption of rate-limit headers;

A phrase in the introduction paragraph seems like a more accurate goal:

communicate service quotas so that the client can throttle its requests and prevent 4xx or 5xx responses.

3. Simplify API documentation avoiding expliciting rate-limit fields semantic in documentation.

the third goal would be clearer stated as:

Simplify API documentation by eliminating the need to define custom quota related header fields.

[darrelmiller]

While this is true, what I want to get rid of is the limit communicated via pdf or web pages, eg.

This is an interesting distinction that I hadn't realized from the original wording. How about the following?

Simplify API documentation by eliminating the need to include detailed quota limits and related header fields in API documentation.

[ioggstream]

I created #32 integrating @darrelmiller considerations with goal 3.

I have some doubts on the other proposal of replacing

Improve resiliency of HTTP infrastructures simplifying the enforcement and the adoption of rate-limit headers;

with

Communicate service quotas so that the client can throttle its requests and prevent 4xx or 5xx responses.

because the goal of the spec is actually to "simplify the enforcement and the adoption" ratelimit headers

@unleashed wdyt?

[unleashed]

I think this conveys two different goals: trying to avoid these 4XX/5XX responses vs simplifying adoption... and I think we want both of these! :)

[ioggstream]

Let's do it :)