raml-org
add a "deprecated" property to resources/methods/parameters
It is quite common to see APIs describing some of their methods, resources and even parameters as being deprecated. This is currently done via text in the description field.
I'm currently using a deprecated trait that only contains a description (which raml2html conveniently adds to the endpoint documentation). It would be nice to have this in a more official capacity (RAML 1.0, anyone?) with more flexibility to document specifics about the deprecation such as replaced by <<METHOD>>, going away in <<VERSION>>, going away on <<DATE>>, and so forth.
Would it make sense to have this as a RAML 1.0 candidate? There are some interesting challenges when you dive in, such as how you would indicate what something is being replaced by -- would you do it programmatically, by pointing somehow to another part of the RAML spec?
On Mon, Mar 16, 2015 at 8:03 PM, Chris Petersen [email protected] wrote:
I'm currently using a deprecated trait that only contains a description (which raml2html conveniently adds to the endpoint documentation). It would be nice to have this in a more official capacity (RAML 1.0, anyone?) with more flexibility to document specifics about the deprecation such as "replaced by <>", "going away in <>", "going away on <>"
— Reply to this email directly or view it on GitHub https://github.com/raml-org/raml-spec/issues/132#issuecomment-81980815.
@usarid I haven't checked the 1.0 spec (honestly still haven't found where it's all collected), but if there are any reference type schemes designed to support HATEOS, I would think that this could be done in a similar way. The overall format below is probably more verbose than I'd really want, but something like !ref could work:
version: 1.0
/endpoint:
deprecated:
replacedOn: 2015-01-01
replacedVersion: 2.0
replacedBy: !ref /newEndpoint
It's right here: https://github.com/raml-org/raml-spec/milestones/v1.0
Are you bringing up HATEOS because you're seeing a linking relationship of type "replaced by" (or somesuch) between two resources? In general right now RAML doesn't have any provisions for HATEOS or resource linking, though I know people have used it for that (don't ask me for a link, I don't have one yet ;-)). But even if we had resource-level references, what about parameters that have been replaced, or parameters that have been combined into a single parameter, or split into multiple parameters, or some other combinations? In general it feels impossible to capture all possibilities. But we could try to capture some, then have the rest just be humanly-readable descriptions
On Tue, Mar 17, 2015 at 7:55 PM, Chris Petersen [email protected] wrote:
@usarid https://github.com/usarid I haven't checked the 1.0 spec (honestly still haven't found where it's all collected), but if there are any reference type schemes designed to support HATEOS, I would think that this could be done in a similar way. The overall format below is probably more verbose than I'd really want, but something like !ref could work:
version: 1.0/endpoint: deprecated: replacedOn: 2015-01-01 replacedVersion: 2.0 replacedBy: !ref /newEndpoint
— Reply to this email directly or view it on GitHub https://github.com/raml-org/raml-spec/issues/132#issuecomment-82632444.
Yeah. I'm not personally a fan of HATEOS but figured if there were already plans for a resource reference type (which it turns out there aren't) a replacedBy property could be another use for it.
I would say that for deprecated endpoints, users should rely pretty heavily on descriptive text -- as you said there are way too many variables to be concerned about, and developers should be expected to read the documentation of the new target to make sure it's going to be used properly (different auth schemes, arguments, schema, etc). At most I'd recommend adding a description property under the aforementioned deprecated tag to allow for documentation specific to the deprecation (especially useful for cases when the more specific properties don't make sense).
Then again, things should also be balanced out for a more simplistic case, which leaves you with a bunch of options:
/endpoint:
deprecated: true
/endpoint:
deprecated:
description: Deprecated because reasons.
/endpoint:
deprecated:
description: Deprecated because reasons.
replacedBy: !ref /newEndpoint
All the way to an enterprise-style endpoint with a deprecated endpoint that might survive for an entire version, where you want to document its entire planned lifecycle:
version: 2.0
/endpoint:
deprecated:
description: |
Deprecated in 1.0 and with plans of replacing it in the next version.
Please avoid using this unless you have to.
deprecatedOn: 2015-01-01
deprecatedVersion: 1.0
replacedOn: 2016-01-01
replacedVersion: 3.0
replacedBy: null # new !ref endpoint coming in v3.0 docs!
This last one is definitely overkill, but maybe it's nice to have an idea of how much is too much.
@aldonline @usarid I think that is subsumed by introducing annotations and annotation types #174. You could easily define an "deprecation" annotation type and defining the necessary properties for that. This type can be then used to annotate a resource or a method to indicate if something is deprecated. You could even annotate the API itself as deprecated.
The issue with annotations is that, by definition, they're not a part of the standard so processors needn't support them and they're not standardized. They're great to foster the kind of exploration that eventually leads to better standards, but we should recognize that when we move something to "do it via annotations" status, we're basically saying it's not the right time to standardize. That may in fact be the correct answer here, just wanted to raise this awareness.
The question is how we leave that, shall we move it or let it as it is for now? @usarid
Right now it's not accepted so we should move it to the not-accepted pile, but the whole point of this period is to get the last round of feedback in before we tie a bow around RAML 1.0
Let's move it. If there is someone really crying for it we move it back ;)
I would like to add my voice into seeing this. As a developer who needs to provide backwards compatibility with our APIs and a company that has strict guidelines around deprecation timelines, proper identification of deprecated properties, endpoints, and APIs is critical for customer communication. In particular, being able to document the end of support target.
I would also like to add a vote to add a way to deprecate properties. This allows an API to be modified.
