API stability level

[chriskapp]

Hi, I would like to discuss with you the idea to define a standard HTTP header which simply describes the stability of a specific endpoint. I.e. if a user requests /my/endpoint then the response could include a stability header i.e. Stability: stable or Stability: deprecated which basically indicates the stability of an endpoint.

At first this provides for users directly an information about the stability and it could be also used at client SDKs to create fitting log entries in case an API becomes deprecated. We can of course discuss the concrete header name and stability values. We could also take a look at other projects who have already defined a stability index i.e. https://nodejs.org/api/documentation.html#stability-index

The header simply returns the current stability of an endpoint it does not contain any information at which point in time this status changes. If a user wants to indicate that the endpoint becomes unresponsive he may can use the Sunset header. So please let me know in case there are already existing ideas or specifications to solve this problem and also let me know your thoughts.

[asbjornu]

The Deprecation header I-D by @sdatspun2 and @dret seems to be related to what you ask for. But I wonder why the Sunset header isn't sufficient? A resource that doesn't return Sunset should be considered stable, no?

[mnot]

My .02 -- this sort of information is a poor fit for response headers, because they are naturally (although not formally) scoped to that response. The normal scope of a concept like "API stability" is whatever the server defines an API; almost certainly something bigger than a single response, and likely something bigger than a single resource.

If this sort of thing is associated with a response, you have an immediate problem in determining what to do / think when you receive multiple conflicting responses about the same API.

Adding lots of stuff like this to all responses isn't great for performance or efficiency either.

To me, it makes more sense to include this sort of information in some kind of runtime descriptive resource -- something like OpenAPI, but specifically for runtime parameters. If there are different levels of stability (or whatever) in the different parts of the API, it should have the flexibility to describe that.

And yes, that could be said about Sunset and friends too...

[chriskapp]

@mnot thanks for your insight and indeed those information should be also included in a specification. The use case which I see is more related to code generation, so lets say you have generated a client SDK based on a specification. Then this specification evolves over time but the generated client SDK does not automatically update to the latest version. Through such an header the server would have an option to somehow provide an information to the client, that the called operation is deprecated and the client could create i.e. a fitting log entry.

The question about the scope of a concept like "API stability" is really interesting. In my view I think more in terms of operations instead of resources, an operation is invoked if you call a specific HTTP method and path. An operation in the end invokes a function/method on your server which triggers you business logic and produces a response. If we think about working with programming languages, we often deprecate specific methods. In the same sense I would see it to deprecate specific operations (HTTP method + path). So I would not see an API as one thing which has a stability but instead a multitude of operations where each operation has an individual stability. But this is of course only my take which is maybe not fitting for other use cases.

[sdatspun2]

Hi Christoph, I am wondering if you are looking for something that is discussed over at #9? Thanks. sanjay

…

On Sun, Mar 12, 2023 at 4:59 PM Mark Nottingham ***@***.***> wrote: My .02 -- this sort of information is a poor fit for response headers, because they are naturally (although not formally) scoped to *that response*. The normal scope of a concept like "API stability" is whatever the server defines an API; almost certainly something bigger than a single response, and likely something bigger than a single resource. If this sort of thing is associated with a response, you have an immediate problem in determining what to do / think when you receive multiple conflicting responses about the same API. Adding lots of stuff like this to all responses isn't great for performance or efficiency either. To me, it makes more sense to include this sort of information in some kind of runtime descriptive resource -- something like OpenAPI, but specifically for runtime parameters. If there are different levels of stability (or whatever) in the different parts of the API, it should have the flexibility to describe that. And yes, that could be said about Sunset and friends too... — Reply to this email directly, view it on GitHub <#15 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFDA3RON7JY4PPZDBFONIHLW3ZPMLANCNFSM6AAAAAAVYB5N4A> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[chriskapp]

@sdatspun2 thanks for the pointer, the health check spec looks interesting, but if I understand this correctly, it does not try to provide some sort of API stability information

[dret]

hello.

On 2023-03-13 02:59, Sanjay Dalal wrote: I am wondering if you are looking for something that is discussed over at #9?

in my mind home documents a la https://datatracker.ietf.org/doc/draft-nottingham-json-home/ would be a better fit for this scenario, but it would be interesting to discuss the relationship of health and home documents (both of which are not standardized at the moment). cheers, dret.

…

-- Erik Wilde | ***@***.*** | | https://youtube.com/ErikWilde |

[dret]

hello mark.

On 2023-03-13 00:59, Mark Nottingham wrote: My .02 -- this sort of information is a poor fit for response headers, because they are naturally (although not formally) scoped to /that response/. The normal scope of a concept like "API stability" is whatever the server defines an API; almost certainly something bigger than a single response, and likely something bigger than a single resource.

exactly. and what an API is is hard (or impossible) to tell by just looking at individual resources.

If this sort of thing is associated with a response, you have an immediate problem in determining what to do / think when you receive multiple conflicting responses about the same API.

correct. https://www.rfc-editor.org/rfc/rfc8594#section-5 specifically talks about the scope of the information received in the header field.

Adding lots of stuff like this to all responses isn't great for performance or efficiency either.

the pattern i usually recommend is to respond with sunset info on specific resources of the API and not on all of them. these could be home and/or healthcheck resources or whatever else you may have in place that's supposed to "represent the API in its entirety".

To me, it makes more sense to include this sort of information in some kind of runtime descriptive resource -- something like OpenAPI, but specifically for runtime parameters. If there are different levels of stability (or whatever) in the different parts of the API, it should have the flexibility to describe that.

in my mind it would be very useful to think once again about home and/or healthcheck documents because that's the very role that they play. there are expired drafts for both of these concepts, but having something that we could point to that's an actual spec (or a draft under active development) would be great.

And yes, that could be said about |Sunset| and friends too...

agreed. i think sunset does an ok job of addressing this in the section linked above, but i have no idea how much this pattern is used in practice. thanks and cheers, dret.

…

-- Erik Wilde | ***@***.*** | | https://youtube.com/ErikWilde |