openAPI: . vs / for parameters

[maxthomas]

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.

thanks again!