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:

• 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? 🤔

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 Changes in api namespace and serialization #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).

[MacTwister]

After a few years of stagnation and with the API blocking further Rails upgrades, I decided to take the plunge and remove the old rocket_pants-based API.

A quick dive into the recent access logs showed only two endpoints with meaningful traffic:

• GET /0/me.json (~10k requests, OAuth clients)
• GET /0/labs.json (~1k requests, researchers/analysts)

As pointed out in previous posts, the gap between documented and actual API usage made it clear that a fresh start was needed. I’ve moved forward with a new API under www.fablabs.io/api.

I recognize the effort that went into the previous API, and I could have kept the old routes running without the gem. However, with only a handful of routes in use—and little context on their original purpose or users; starting fresh makes maintenance simpler and more sustainable for the future.

I have implemented these initial routes to start of with:

• /api/me (same controller as before)
• /api/labs (same logic as /0/labs.json)
• /api/users (same logic as before, for academy scripts)

A nice side effect: OAuth now runs on the main www. subdomain, so users won’t need to re-login as they did with the old api. subdomain.

The old API subdomain will return 404s for all routes (except OAuth, which will remain until clients migrate), allowing us to monitor lingering traffic. The previous /2/ API followed the json:api spec—something we can revisit if desired.

This change unblocks the Rails upgrade and gives us a clean foundation. Feedback and ideas are welcome—let’s build from here!

[zeno4ever]

FYI I use the endpoint https://api.fablabs.io/0/labs.json for my mapall.space website.

My aim is to have a list of active fablabs and show this on a worldwide map. This kind of works only problem (but this is not a software problem) is that some fablabs are closed but still on the list. As far I know there is no active checking if a space is still open.

If you have any questions about my usage, just let me know!

Regards,
Dave

[MacTwister]

Hi @zeno4ever,

Thanks for sharing your use case and the context around mapall, nice project! Reading your message actually made me reconsider the plan to redirect the old /0/labs.json endpoint. I’ll keep it active for a while longer, even though most HTTP clients handle redirects just fine.

This will give us more time to brainstorm if there’s interest in changing how the labs endpoint works (e.g., response structure, pagination, filtering), or if we should keep the same logic on the new URL. I am going to focus on the rest of the upgrades first.

How to handle closed labs is an interesting discussion—something for a new issue to explore that further.

Cheers!