Backoff time

[merkys]

Fixes #409 by introducing request_delay, an optional field in meta of any response to ask the client to wait specified number of seconds (float) before issuing subsequent request.

[dwinston]

Given that HTTP is assumed as the API access protocol, we can also leverage the standard Retry-After response header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After.

[merkys]

@dwinston fair point. I will adjust the proposal to add Retry-After.

[rartino]

Consider moving the error code suggestion as discussed.

[ml-evs]

A useful addition to the spec!

Do we prefer request_delay instead of just using the same nomenclature as retry_after? One minor formatting comment below.

[rartino]

Thanks for the work with this. Some suggestions to consider.

[rartino]

I think this belongs elsewhere - the SHOULD-level requirement that server return the Retry-After http header in a 429 response should apply regardless of whether the request_delay field is used or not.

[merkys]

Right, this has already been discussed, and we agreed it should be moved elsewhere.

[rartino]

@merkys Do you intend to make this change? (Or do you want someone to help?)

[merkys]

@rartino yes, I intend to do so, but it would help me a lot to know where exactly should I move this text.

[rartino]

I think the only place that makes sense is https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#http-response-status-codes

[merkys]

Ah, right, will move soon.

[merkys]

But do we really need this text then? Currently, "HTTP Response Status Codes" and "HTTP Response Headers" are pretty concise, only providing pointers to HTTP and JSON API standards. Do we want to duplicate that locally? HTTP 429 and HTTP Retry-After seem to be pretty standard.

[rartino]

I'd say no, but there were others pushing for this info. I think the primary problem I have with just leaving what you have as it is, is that it adds a requirement on HTTP headers in a section that is, in a sense, not strinctly tied to HTTP as the transmission protocol. I'll try to suggest a requirement-free version.

[merkys]

Thanks for the suggestion, I have accepted it. I like that HTTP 429 and Retry-After are now in an implementation note. This way OPTIMADE specification does not add specific interpretation on top of HTTP standards.

[merkys]

@ml-evs

Do we prefer request_delay instead of just using the same nomenclature as retry_after? One minor formatting comment below.

I would indeed prefer sticking to the same nomenclature, but "retry" part does not sound right here. I would expect "retry" to mean "issue the exact same request". Maybe next_request_after or just request_after sounds better?

[JPBergsma]

This PR seems good to me.

[rartino]

@ml-evs, @merkys

Do we prefer request_delay instead of just using the same nomenclature as retry_after? One minor formatting comment below.

I would indeed prefer sticking to the same nomenclature, but "retry" part does not sound right here. I would expect "retry" to mean "issue the exact same request". Maybe next_request_after or just request_after sounds better?

As a remark: I first though the http header retry_after was not appropriate at all outside delivering an http errors. However, digging a bit in the RFCs made me realize that while the latest RFC allows it to be used also the way we say. The reason for the name is thus "historical debt".

Nevertheless, I agree with @merkys to rather just use a more helpful term.

[ml-evs]

Fine by me!

[rartino]

Good to go!

[ml-evs]

I think I slightly preferred the SHOULD/MAY formulation, but this still looks good to me.