More programmer-friendly API docs

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 :smiley:

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 :slight_smile:

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ā€¦

6 Likes

A couple of things worth saying:

  • 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.
  • there isnā€™t a single API, there are multiple

But to address your question about an overview

have a look here

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.

  1. 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.
  2. 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.
  3. 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.

3 Likes

3 posts were split to a new topic: Help with API for views/documents

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.

This is not really helping I think

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 :stuck_out_tongue_winking_eye:

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ā€.

Hey Nevil,
Your feedback is clear, and weā€™ve noted it. Weā€™re not skipping over it.