search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.99k stars 9.07k forks source link

Ability to define a API-level and method-level timeouts #695

Open mm-gmbd opened 8 years ago

mm-gmbd commented 8 years ago

Considering there are several tools out there for generating both client-side and server-side code from your OpenAPI spec, defining timeouts would be a useful feature, imo. I would think an API-wide timeout and method-level timeouts (i.e. generators would see if a method had a method-level timeout, and if not, it would use the API-level timeout).

Looking at the specification I didn't see any mention of this, and I didn't see the word "timeout" in any issues, but I figured I couldn't be the first person to bring this up... maybe I'm missing something?

For now, I'll add it as a vendor-level extension, but it would be nice to be officially supported.

ePaul commented 8 years ago

Is a timeout really a property of an API? What would be its meaning?

mm-gmbd commented 8 years ago

With the emergence if IoT, it is becoming more and more common for APIs to actually interact with real devices (that is the perspective I am approaching this from).

In some cases, an API request to an IoT device may require the device to perform a real-world, non-instant operation. If this operation takes a known amount of time, which may be longer than most clients would wait to declare a timeout, this can be extremely useful.

As for it's meaning -- I think that is fairly clear already (but, the answer always seems easier if you know it ;)). If there is a consumer of the API, and a timeout is defined for a particular method/operation, then the consumer could/should wait the specified period of time before declaring a timeout.

ePaul commented 8 years ago

So it is something like "expected upper limit of the duration of an operation"?

mm-gmbd commented 8 years ago

That sounds fine -- potentially remove "expected".

fehguy commented 8 years ago

This really feels "use case specific" rather than API general.

mm-gmbd commented 8 years ago

Can you elaborate? My thought is (not surprisingly) the opposite. It may seem "use case specific" if you're only used to clients communicating with servers that should compute and return data in the sub-second timeframe, but operations are not always going to happen that fast (especially if there are physical/hardware limitations that require some amount of time to pass before verification) in the IoT realm. I would think that OpenAPI would aim to be the API of choice for the (many) IoT implementations coming down the pipeline.

fehguy commented 8 years ago

You mean you want the provider to say "this is slow" in the metadata?

We are working on asynchronous response definitions, which is probably the way this sort of thing will be described in the IoT world.

When I say "use-case specific", I mean that depending on how you're using the API, you may be more tolerant to long-running operations than with other cases (like, high volume). So in that case your acceptable timeouts would be significantly different.

mm-gmbd commented 8 years ago

Your use of "slow" vs. "fast" seems like a difference of perspective - "slow" would be slower relative to the normal/average speed at which you are accustomed to receiving responses from some service.

When the endpoint changes from a server computing/returning data to a physical device performing real-world operations, your use of "slow" would actually be the expected speed of the requested operation - to me, this is different than trying to boil it down to the (inherently relative) "slow" vs. "fast".

However, with other cases you mentioned such as high-volumes of requests (or even just a "slow" internet connection), this does start to complicate the discussion more, so I can see the reservation from that perspective. Also, asynchronous response definitions sound like a potential candidate to represent this scenario.

webron commented 8 years ago

While not exactly the same, this seems potentially related to #541.

vtolstov commented 3 years ago

any progress?

rober15 commented 11 months ago

Wonder if there is any answer on this several year old topic (i just see many linked issues around this but no solution) The post came 2016 or do i miss what solution has been offered. I agree 100% that a timeout set on an API should be known by caller. Otherwise you get into situations where you call API the api times out but process runs further and caller gets an time out error. So you would retry and then on next call it would tell you that record already exists (likely another error). So you never got a http 2xx back which is really bad. So caller timeouts should be always and ideally set higher as the API timeouts. Without knowing the API timeout settings you have no chance to consider that.

Can any of you maybe help to get some clarity on that topic: @darrelmiller @whitlockjc @earth2marsh @MikeRalphson @webro @usarid

Many thanks.

SSYH commented 11 months ago

address/ed in SLA4OAS? ( ref @ePaul )

lornajane commented 11 months ago

@rober15 please don't at-mention individuals, they get plenty of notifications as it is.

Perhaps someone already implemented this as a vendor extension, and could share an example for you to adapt to your own needs? Rest assured that if there are any change to the status of this issue, the issue will be updated.

dmitry-auto1 commented 9 months ago

I'm also interested in this feature.

hw-claudio commented 2 months ago

also interested. Not all APIs are about a web interface.

Some operations have very specific lower or upper bounds on the time required to execute.

I am designing an API right now, and I have no way to express in the API that I know very well that the operation will take many seconds, and should timeout at 90 seconds.

It would be very useful for the API consumer to know this, so yes, this should be in the scope of a specification like this.