Supporting Retry Policy and Timeout configuration for each Operation

[pinalbaldha]

Having retry config & timeout in the spec, clients will retry errors for a given an operation based on the provided retry configs and shouldn't retry errors which are not retriable.
In a way, retry config is part of API contract.

Sample spec:
which says if Operation CreateBook fails with error 500 or 503 then the operation should be retried based on the given configuration.

paths: 
  /v1/shelves/{shelfId}/books/: 
    post: 
      opreationId: "CreateBook"
      requestBody: 
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Book'
      responses: 
        '200': 
          description: "Book Created" 
        '401': 
          description: "Unauthorized"       
        '500': 
          description: "Request cancelled"
        '503': 
          description: "Server unavailable"
      retryPolicy: 
        maxAttempts: "3"
        initialBackoff: "20s"
        maxBackoff: "60s"
        backoffMultiplier: "1.5"
        retryableStatusCodes: 
        - "UNAVAILABLE"
        - "CANCELLED"
        timeout: "300s"

Inspiration: https://github.com/search?q=repo%3Agoogleapis%2Fgoogleapis+path%3Aservice_config.json+retryPolicy&type=code

Any thoughts / suggestions?

[ralfhandl]

What's the benefit of having this static information in the machine-readable description over sending a retry-after response header, where the concrete value can be adjusted depending on current use/load/...?

[pinalbaldha]

A Retry-After response header serves the similar purpose, even it can be adjusted dynamically based on various factors.
But along with that, having static configuration could be beneficial.

All/Most of the clients implement default/automated Retry Behaviour (no of attempts, back_off, timeout, condition_to_retry etc). It helps with the cases where Retry-After header is not sent. (i.e request timed out, no response from server). In Many documentations, observed the segment like "maybe Retry-After will be sent" and mainly it is used with [503 / 429 / 301] status codes only.
Most systems implement good retry strategy & circuit breaker instead of just relying on retry-after header.
Having RetryPolicy in the spec, one can specify retryable status codes & it's configs beforehand.

[karenetheridge]

I could see this information being useful for webhooks or callbacks -- that is, requests initiated by the API provider, that will retry again after a pre-indicated time if the initial request is rejected or the server is unresponsive.

This is totally orthogonal to the "Retry-After" header, which is used in API responses that use the 30x, 429, or 503 response codes.

[rafalkrupinski]

Is the timeout for connect, read or total timeout? I think those values depend on data and network setup (larger data needs larger timeouts, but different networks have different maxima), don't they?