Update API reference section to be under `/api` but link to files under `api-clients`

seamapi / docs

Welcome to the Seam Docs.

https://docs.seam.co

4 stars 10 forks source link

Update API reference section to be under `/api` but link to files under `api-clients` #304

Closed razor-x closed 2 weeks ago

razor-x commented 1 month ago

We need to turn every item under 📋 API Reference <a href="#api-clients" id="api-clients"></a> in SUMMARY.md to match the final structure, and we need to rename the files to match.

For example,

- * [Access Control Systems](api-clients/access-control-systems/README.md)
+ * [Access Control Systems](api-clients/acs/README.md)
-  * [Systems](api-clients/access-control-systems/systems/README.md)
+  * [Systems](api-clients/acs/systems/README.md)
-    * [List Systems](api-clients/access-control-systems/systems/list-systems.md)
+    * [List Systems](api-clients/acs/systems/list.md)

razor-x commented 1 month ago

mikewuu commented 1 month ago

List Systems

List Systems

@razor-x It seems like the convention is to have the resource name (systems) in the file name. Do we want to deviate from convention for acs only, and rename this to just list.md?

razor-x commented 1 month ago

Yes we want the urls names to exactly match the API routes they document. So /api-clients/acs/systems/list.md is correct.

We need to do this for all of the files not just ACS. This is needed so we can incrementally migrate to the generated files.

razor-x commented 3 weeks ago

These pages still resolved old / incorrect links. Need to verify a fix for each one before we can close this issue.

[ ] /api/workspaces/reset-workspace
[ ] /api/connected_accounts/update-a-connected-account
[ ] /api/devices/device-provider-metadata
[ ] /api/devices/list-unmanaged-devices
[ ] /api/devices/get-an-unmanaged-device
[ ] /api/devices/update-1
[ ] /api/devices/delete-a-device
[ ] /api/access-codes
[ ] /api/access-codes/get-an-access-code
[ ] /api/access-codes/list-1
[ ] /api/access-codes/delete-1
[ ] /api/acs/entrances/list-entrances
[ ] /api/acs/access-groups
[ ] /api/thermostats/list-thermostats
[ ] /api/thermostats/get-thermostat
[ ] /api/thermostats/climate-setting-schedules (being removed anyway, but everything under this path is incorrect)

razor-x commented 3 weeks ago

@mikewuu I opened the PR from beta to main and the links are still incorrect. This is top priority to fix since then we can merge just the renames and avoid merge conflicts due to all the renames.

razor-x commented 2 weeks ago

@mikewuu This PR should do it: https://github.com/seamapi/docs/pull/321

I didn't include any of the URL updates for the files outside of api-clients. Let's open a separate PR with those changes to reduce size / risk of merging this one.