hi there! first, love the project and hope that the maintenance issues can get resolved; it'd be awesome to keep this going.
i was looking at the OpenAPI spec and noticed that many of the path parameters contain either:
a suffix of .json, for endpoints that (presumably) return JSON data e.g. /api/2/devices/{username}.json. i'd think omitting .json and just returning JSON would suffice there, or was there some other consideration?
contain multiple path parameters separated by . and not / - this causes issues with tooling (more later)
some things don't seem very DRY, ie lists API contains a username path parameter then /list again
some APIs aren't versioned e.g. subscriptions, while others are (with eg /api/2/devices)
while the current openapi.yaml may be a valid OpenAPI spec, it's problematic from my perspective for a few reasons:
openAPI clients struggle with path parameters containing ., but are purpose built to handle / path parameter delimiters. for example, /subscriptions/{username}/{format} is easily handled by virtually any server-code generating OpenAPI library i've tried, whereas {username}.{format} is not handled well by... virtually any of them.
similarly, the use of .json as a suffix for path parameters causes issues in libraries who assume (perhaps wrongly) that a path parameter is the entire parsed path, ie {username} and not {username}.json. i'd suspect that the default content type would be JSON throughout, anyway, which again, might reduce some repeating.
i know these are significant API changes, but it might help developers better integrate with the mygpo ecosystem, as it'd be easy to generate clients/servers/etc. that may eg be more performant or easier to self-host than the python impl of mygpo.
would y'all be open to some day releasing a v3 of the OpenAPI spec with any of these changes? i understand it's probably very very low priority but might be good to think about, otherwise, the openAPI integration is a little difficult.
hi there! first, love the project and hope that the maintenance issues can get resolved; it'd be awesome to keep this going.
i was looking at the OpenAPI spec and noticed that many of the path parameters contain either:
.json, for endpoints that (presumably) return JSON data e.g./api/2/devices/{username}.json. i'd think omitting.jsonand just returning JSON would suffice there, or was there some other consideration?.and not/- this causes issues with tooling (more later)listsAPI contains ausernamepath parameter then/listagainsubscriptions, while others are (with eg/api/2/devices)while the current
openapi.yamlmay be a valid OpenAPI spec, it's problematic from my perspective for a few reasons:., but are purpose built to handle/path parameter delimiters. for example,/subscriptions/{username}/{format}is easily handled by virtually any server-code generating OpenAPI library i've tried, whereas{username}.{format}is not handled well by... virtually any of them..jsonas a suffix for path parameters causes issues in libraries who assume (perhaps wrongly) that a path parameter is the entire parsed path, ie{username}and not{username}.json. i'd suspect that the default content type would be JSON throughout, anyway, which again, might reduce some repeating.i know these are significant API changes, but it might help developers better integrate with the
mygpoecosystem, as it'd be easy to generate clients/servers/etc. that may eg be more performant or easier to self-host than the python impl ofmygpo.would y'all be open to some day releasing a v3 of the OpenAPI spec with any of these changes? i understand it's probably very very low priority but might be good to think about, otherwise, the openAPI integration is a little difficult.
thanks again!