initial openapi3 spec - Githubissues

schristley commented 5 months ago

Formalize the OGRDB API as an OpenAPI V3 specification as part of the AKC effort.

schristley commented 5 months ago

Hi @williamdlees here is a starting spec. There are a few initial decisions I made that we should discuss and/or get your feedback on. I didn't implement all of the endpoints, just a few so that we can see what it looks like.

I arbitrarily picked a version of 1.0.0 for the API.
I used a base URL of /airr/ogrdb/v1 to put the API under the "AIRR" umbrella.
For species, I switched to an ontology object. I think this is something we've talked about so that can be precise with IDs instead of relying upon text string.
For the endpoint that returns the actual GermlineSet, I have the response object in a similar form as the ADC API.
Also, I did run the spec through pydantic so there shouldn't be any spec errors. Do you have a test suite setup for the GitHub repository? Kind of like what AIRR standards does. It would be good to have something so that syntax errors and such can be caught early.

schristley commented 5 months ago

Here's essentially what I did to validate the spec

from openapi_pydantic import parse_obj, OpenAPI, PathItem, Response
x = yaml.safe_load(open('ogrdb-api-openapi3.yaml','r'))
open_api = OpenAPI.model_validate(x)

williamdlees commented 5 months ago

Hi Scott,

Thanks, this looks good. Let’s call this v2.0.0, that way even though v1 isn’t called v1, we acknowledge its existence.

I’ve added an automated pydantic check (on this branch) and it appears to be passing.

All the best

William

From: Scott Christley @.> Sent: Friday, April 12, 2024 6:42 PM To: airr-community/ogrdb @.> Cc: William Lees @.>; Mention @.> Subject: Re: [airr-community/ogrdb] initial openapi3 spec (PR #98)

Hi @williamdlees https://github.com/williamdlees here is a starting spec. There are a few initial decisions I made that we should discuss and/or get your feedback on. I didn't implement all of the endpoints, just a few so that we can see what it looks like.

I arbitrarily picked a version of 1.0.0 for the API.
I used a base URL of /airr/ogrdb/v1 to put the API under the "AIRR" umbrella.
For species, I switched to an ontology object. I think this is something we've talked about so that can be precise with IDs instead of relying upon text string.
For the endpoint that returns the actual GermlineSet, I have the response object in a similar form as the ADC API.
Also, I did run the spec through pydantic so there shouldn't be any spec errors. Do you have a test suite setup for the GitHub repository? Kind of like what AIRR standards does. It would be good to have something so that syntax errors and such can be caught early.

— Reply to this email directly, view it on GitHub https://github.com/airr-community/ogrdb/pull/98#issuecomment-2052199759 , or unsubscribe https://github.com/notifications/unsubscribe-auth/ACXBI7LFIW652SVW4U5LAS3Y5AMHFAVCNFSM6AAAAABGEQLD2GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJSGE4TSNZVHE . You are receiving this because you were mentioned.Message ID: @.***>

airr-community / ogrdb

initial openapi3 spec #98