Consolidate API documentation and implementation

[pral2a]

Current API documentation is not working at all. Also most of the examples related to the API are not working neither. Actually, there are 3 API versions but none of them is properly documented leading to a lot of difficulties to use the API, mostly for externals.

My suggestions are:

• [ ] Asses documentation and API version status
• [ ] Reduce the number of end-points to be supported and maintain only one API version
  • [ ] Confirm what end-points are used by "fabcloud" mgmt scripts
  • [ ] Provide basics methods (labs, machines...) with filter capabilities focusing in Rails standards to reduce maintenance efforts
• [ ] Create basic documentation with methods and payload examples
• [ ] Remove unsupported old documentation or clearly indicate as legacy

-- Viktor edit:

• [x] Archive / delete the repo https://github.com/fablabbcn/docs.fablabs.io
• [ ] Remove the DNS record for docs.fablabs.io
• [ ] Stop using unmaintained rocket_pants gem which is preventing Rails 6 update

Problems:

• The API doc is very much outdated. https://docs.fablabs.io/
• Do we need a specific api.fablabs endpoint?
• Can we do with a simple .json endpoints which use Ransack query / filter / paginations
• https://api.fablabs.io/ - says it's READ ONLY. Is it? :thinking:

This now redirects to the API, why? https://fablabs.io/labs.json redirects to -> https://api.fablabs.io/0/labs.json which loads ALL labs.

Suggestions

• Can we do with a minimal API? Do we need the v0 / v1 / v2
• Do we need a versioned API? Do we have the resources to maintain it?
• Remove / minimize the outdated documentation? Do we have the resources to maintain it?
• Use simple .json endpoints
• https://api.fablabs.io/0/me.json <-- Needs to keep working

Related #444 #464 #76 #71 #72 #73

[viktorsmari]

Another thing is that the API versioning functionality is using a deprecated gem called rocket_pants

This gem is preventing us to update to Rails 6

It prevented us also to update to Rails 5, but we found a maintained fork of it, which is now also not maintained.

https://github.com/Sutto/rocket_pants <-- last update 2015 https://github.com/parse/rocket_pants <-- last update 2018 (fork of the previous, we are using this one)

[MacTwister]

Some input from my side as Viktor shared this with me.

1. For the Fabacademy student scripts, we are mainly interested in the users endpoint (searching and creating user accounts).

Another thing is that the API versioning functionality is using a deprecated gem called rocket_pants

I'm not so bothered if you would like to move the API to fix controller instead of using that gem. (if you guys are sure nobody else uses those APIs). Do you have any usage analytics on API request? Then let's align on the exact changes, to prepare for the next cycle.

2. The OAuth (Doorkeeper) stuff uses the api.fablabs.io URL, not sure where/why this comes from. I only know this when setting up Gitlab and other auth stuff to work with Fablabs.io (probably this could move to the www. domain without breaking auth flows, but needs testing).

3. Continuing on the Auth flow, (maybe related to #444 ), the Gitlab and other platforms that login with FablabsIO, will fetch profile information after authorization, using the URL https://api.fablabs.io/0/me.json. Not sure if related to the versioning stuff, but so you know to make sure it doesn't break.

   Edit: Not using this package, but see fibasile/omniauth-fablabs an example how it's used.

4. Seems like a good idea to switch to the basic "get" api stuff for normal users to use the .json rails/integrated stuff. Which would be cleaner for those simple tasks (eg. like students doing research or graphs), though I'd review what information you are output ing to make sure no private information is leaking on any of those end points (ie. users/xxxx.json does not leak the email).