[docs]: Update Backend REST API for v3

[BenJamesBen]

Where can we see the problem? 🤔

https://freesewing.dev/reference/backend

Are you a FreeSewing patron? 😃

Yes, I am a tier-2 patron ❤️

Suggested content

The Backend REST API needs to be updated with v3 changes.

The Swagger docs should be an accurate representation of the API, so we can follow its lead: https://backend3.freesewing.org/docs/#/

Additional context

No response

[BenJamesBen]

@joostdecock Should the freesewing.dev backend API docs use the same language that I see in the Swagger/OpenAPI? For example, should the language in the docs be "retrieve" and "remove" API keys instead of the currently-used "read" and "delete"?

And, the flattening of the docs directory structure, for example /reference/backend/apikeys instead of /reference/backend/api/apikeys, is intentional, correct?

Is the omission of the /admin endpoints intentional? (Are those endpoints non-public?) Or, should they be added to both the OpenAPI and our docs? For example, the "get newsletter subscribers" and "impersonate user".

[joostdecock]

@BenJamesBen The Swagger docs and markdown docs are written somewhat independently, and I don't really mind that there's some differences (like read vs retrieve and so on).

It's obviously not ideal to maintain documentation in two places, but my reasons for doing are:

• The swaggers docs come with an OpenAPI v3 specification, which allows people using automated tools to generate a REST client of our API automatically.
• If we have only the swagger docs, I find it does not leave much room to explain why things are done in a certain why and so on. I also think we should have all docs on freesewing.dev.

All API routes can/should be documented. I write an initial bunch of documentation, but for newer endpoints it has not been written yet.
You see, the newsletter of 1 januari 2024 was the first time we used the v3 backend for the subscribers. The previous edition was still using the v2 backend. Something that I realized on... the 31st of December 2023. So I did what I had to do to make it work buy the next day, but I did not also write docs for it 🤷

As for URLs, the API endpoints have strict URLs, and the docs follow those. But on freesewing.dev something like /reference/backend/apikeys talks about the how/why/what of API keys, so yes, the difference is intentional.

Let me know if you need more clarification.