• import the main.yaml openapispec from WME into https://wmf-openapi-linter.toolforge.org/
• 20 errors and 1400 warnings. Jeez. I'll tackle the errors first.
• The lines reference isn't very helpful, referencing a line range instead of a specific line, and often just referencing lines 0-0
• the errors are all of type 'example property type must be array' or 'example property must match format "uuid"'. all of those errors have reference of lines 0-0, so it's hard to narrow down exactly what they're referring to. There are only two properties with format:uuid and an example, on lines 1961 and 2018.
• removing format:uuid from the properties that have them to see if those errors go away, because the examples are actually formatted as uuids. After more research, it seems that the error stems from the fact that the uuids aren't formatted according to RFC4122 that defines the uuid format. So I'm wrongly adding format:uuid to these properties. They're unique IDs, but not Universally Unique IDs. see OAS Format Registry. So I will not re-add format:uuid.
• the 'example property must be array' seems to be because OAS 3.1. has deprecated the example field in favour of the examples object, which takes an array of examples. See the Example Object. I'm unsure of if these errors are stemming from the examples in parameters or in schema. I'll change all of the examples to arrays in the schema object first to see if the errors go away. The issue with changing from example to examples in the path parameters is that it might break how the example shows on our docsite. Changing from example to examples in schema should not be an issue, since that's not used in the docsite. BUT the OAS warns that 'Because examples using these fields represent the final serialized form of the data, they SHALL override any example in the corresponding Schema Object.'

Following up on this, if we want to normalize endpoints, we could try to follow the WMF API reference documentation guidelines. See Path summary guidelines. I have summarized what these endpoint names would look like if we follow the WMF naming guidelines completely. I personally don't always agree with the guidelines, as described below. The guidelines differ from our internal discussions:

Instead of using the linter first, I've opted to go through the guidelines written by Kamil first, hopefully squashing some linter messages before actually using the linter. Questions that came up while doing so:

• searched for other openapi-based tools on ToolHub
• found some like this and this
• realized these swagger consoles don't resolve their requests with the 'try it out' button because of auth issues when trying to initialize this from the browser console
• Talked to @taavi about openapispecs, and learned that our current implementation of allowing WMCS access through IP_ALLOWLISTING the WMCS IP Range is not sustainable. We should instead pull in the machine-readable IP list from https://meta.wmcloud.org/cloudvps-ips-public.json , documented here https://wikitech.wikimedia.org/wiki/Help:Cloud_VPS_IP_space. Only public API IP list is needed.
• After talking to Taavi, realised that publishing our openapi spec as a swagger GUI on Toolforge will not work auth-wise, since you're still sending the requests from your browser instead of server-side from Toolforge.

Changes made to:

• Meta wiki page for WME
• Data Services Portal
• cloud services introduction page
• WME Getting Started docs
• WME Auth docs

• go to Cloud VPS portal
• go to cloud VPS user docs
• I understand I need to create or join a cloud VPS project to test these calls in Cloud VPS
• Look at existing cloud VPS projects.
• I'm going to assume that if this works on Toolforge or PAWS as expected, this will also be the case for VPS. Joining or creating a Cloud VPS project will take too much time at this hackathon.

• get forwarded to toolforge quickstart. Find 'if you already have the right accounts' section. Get forwarded to toolforgeadmin. Log in. Connect WM account to dev account on toolforge.
• have to set up an SSH pubkey. Go to howto on ssh key gen. Read up on SSH keys, and realize I can probably use the same pubkey I already have and use for other services. Added SSH key.
• lost the thread for a second, found it again in Toolforge quickstart. submitted toolforge membership request. Asked @Lucas_Werkmeister_WMDE if they could pretty please approve request, which they did.
• managed to ssh in using

ssh -i ~/.ssh calvinball@login.toolforge.org

• made the same two example calls above, which again work perfectly in toolforge ssh shell.

Thoughts:

• WME should be mentioned on the following pages: https://wikitech.wikimedia.org/wiki/Help:Cloud_Services_introduction ,