disclaimer: this is a bit of a rant and i may not be aware of the correct resources to look at. if i am missing something obvious please feel free to call me an idiot and link me the good docs
i gotta be honest: as much as i love fibery so far, not having the api documentation in this format Papierkram API but in individual articles in fibery is a total mess. for example say i wanna list all databases for a given space. first one needs to wrap his head around databases being called types (maybe this makes sense further down the line when i know more about fibery, but right now i am just thinking āwtf who thought that this naming would AVOID confusion instead of creating moreā), then the types examples only showcase creating, updating and so on. which is of course nice to have, but maybe i wanna get an overview of whats there first.
the background of me being a bit annoyed about the documentation is that i am in the process of creating a community node for n8n in order to be able to easily integrate fibery with other tools via n8n, as i donāt like make.com and other alternatives like zapier (also one can selfhost n8n). and not having a big picture list of all possible queries endpoints and whatnot has so far cost me multiple hours of my life that i wonāt get back. granted, iām not the smartest person in the world and i am far from being a pro with api stuff. but i felt that other tools i use made it much simpler for me to get a gist of what to query in order to get the desired result.
this would be greatly remedied by having a bog standard default overview of all api possibilities in one of the api documentations pages, like for example here User_Guide/Guide/REST-API-259 . and then have the current documentation with examples in addition to that.
looking forward to any anwers
edit with update: after investing 3 more hours into using the api and slowly getting the info out of it that i need. the deeper i dig into this, the more obvious it becomes how bad the documentation is. iām actively collecting my own documentation on this and will share it here once iām done. feel free to use it to save time and nervesā¦
Fibery terminology has changed over the years, so what are now called Spaces used to be called Apps, Databases used to be called Types. Changing the API to reflect that has not been a priority
the inherent flexibility of Fibery means that API syntax will vary heavily from workspace to workspace, e.g. some databases will have a state field, some wonāt; some will have assignees, some wonāt, etc.
Iām glad to see someone else chiming in on the topic. Iāve been working with the Fibery API regularly since 2021. My skill level at that time was beginner, today Iād consider myself an intermediate, and Iāve worked with software and developer professionals with decades of experience to integrate with Fibery. We all agree that the documentation, especially the approach to documenting the API needs work.
Thereās a range between creating beginner dev friendly documentation and functional documentation for platform experts and Fiberyās API docs lean towards the latter. Itās certainly not as bad as Microsoftās but it has the same pitfalls at a smaller scale.
There is an astounding lack of examples and I donāt understand the determination not to add them. The documentation for the command/query API doesnāt consistently list the various input options for each command. I think esignatures is a great example of how to do this in a minimal, easy to maintain way.
Most often, people are searching for a solution to their specific need, but Fibery documentation is written as if people read it from the beginning, master a concept, and then can refer back to those early concepts to determine the right way to accomplish specific usecases. This is not practical.
There are workarounds of course, for example leveraging the UI as a query generator but consider why this is a preferred method. The documentation is not expansive enough. When I encounter an unexpected error, I review the documentation, notice there is a gap, and use google to find a specific reference to that exact script/api command here in the community. This is because the documentation is not specific enough to assist in troubleshooting errors. To his credit @Chr1sG is almost always involved in producing working code here in the community, but there seem to be no feedback loops that result in improved documentation. I consider the community the best reference for Fibery scripts.
I might point out here that Airtable deployed a custom api doc generator for each base in the late 10ās. That is a luxurious approach. It isnāt necessary, but a great example that flexibility is not a barrier to great docs. At the end of the day, the rules are standard and there are a fixed number of field types.
The old documentation was easier to navigate and reduced some of the friction of having to find and re-read high level concepts when working on a solution. But the new documentation in Fibery further restricts visibility into what documentation exists and where to find it.
I think better documentation would benefit not just a few power users, but overall app adoption as it would make it easier to build, ship, and market the power of Fibery. I have at several points over the years simply put off ideas and projects until I learned Fibery better or in hopes someone else will make headway and post about it to avoid some frustration.
Iām not a programmer by any means, but I understand the basics of a REST API and how it looks and works. The Fibery API is really strangely made, and quite difficult to understand.
Aside from that, the docs are indeed a bit of a mess.
How do all these lines on the flowchart make anything clear at all? And how does the sidebar help? Itās about all sort of different topics except the API.
I would suggest using something clean and simple such as Mintlify and not making your own API docs in Fibery.
To be fair, you are looking at the entire publicly shared Fibery workspace, which contains the Roadmap, Fibery Process and Changelog spaces, as well as the User Guide (which is where the API documentation lives). So saying that it contains lots of topics other than the API is a bit like saying that Microsoftās website contains lots of topics other than how to use Excel formulas
Itās not a flowchart, itās an example of a workspace map (as it says). The workspace map is a visualisation of the workspace schema, so for some people, it helps them understand what they are working with when they query the schema via the API.
There are a lot of tools that could be used to store the API documentation, but there are a couple of reasons why we chose to keep the info in the User Guide:
we can reference other non-api topics so that people who are reading about how to use the API to query an entity, can visit the pages that explain what an entity is
itās simpler from our side to have all our material in one place
the tools that claim to automatically generate lovely API documentation are not very good at coping with the fact that Fibery workspaces are unique. Itās not like there is a standard API query to āget all Projectsā because not every workspace has a Project database. In other words, there is a functionally infinite number of possible API commands that could exist.
Of course, having said all that, there is no doubt that the content could benefit from improvement, but with our limited resources, itās not a priority right now.
Now that you have explained why it is like it is, it still doesnāt change anything about the fact that itās unclear documentation for us. So Iām not sure if you guys received the feedback properly. The above explanations doesnāt make it better for the users, so to speak.
But itās not a priority as I understand, fair enough.
Sure, we get that not everyone appreciates the documentation as it is, but I figured it was worth explaining some of the original decision making for how it is rather than simply saying āyouāre right, itās awful, but we havenāt got time or plans to improve itā.
