search

airr-community / airr-standards

AIRR Community Data Standards
https://docs.airr-community.org
Creative Commons Attribution 4.0 International
35 stars 23 forks source link

deprecate OpenAPI 2 spec for ADC API? #765

Open schristley opened 4 months ago

schristley commented 4 months ago

@bcorrie Any reason to keep the OpenAPI 2 spec now that we have the OpenAPI 3 spec? We aren't doing any consistency checking between the two so who knows if they even match...

bcorrie commented 4 months ago

The only reason I can think of is if any tools are using it and we want to keep it for backwards compatibility. We are not using it, but I could see how someone out there in the wild might be?

schristley commented 4 months ago

The only reason I can think of is if any tools are using it and we want to keep it for backwards compatibility. We are not using it, but I could see how someone out there in the wild might be?

Right, which is even more worrisome in a way because checking consistency between API specs is much harder than for just the schema...

So one way to know is to get rid of it and see if anybody complains! ;-)

schristley commented 4 months ago

I suppose the larger question is do we intend to deprecate at some point, and when is that point? There's nothing particularly special about the AIRR V2 release for the ADC API, but it is a new release so is a chance to do it if we want.

schristley commented 4 months ago

I'll note that we might, though I'm still thinking about this, extract out the ADC API schemas into its own file. Essentially making that one part of the spec look somewhat like this:

components:
    schemas:
        $ref: 'adc-api-schema.yaml'

With two thoughts in mind. One is that for services like VDJServer that automate on the spec, it might be easier to support those extension fields like v_subgroup and such. And two, services like the AKC which may extend those schemas in some way for its own APIs.