The abysmal nature of monday.com API

monday Apps & Developers
,
6

Hey @kolaai,

It takes quite a lot of effort to write a detailed post with so much feedback, and I really appreciate you taking the time to do it. I interpret it as a genuine desire to make our platform better, so thank you.

I won’t be able to do respond to every point in detail, but I wanted to give you some context about the efforts we’re working on internally.

Again, I really love the detail you put into your message!

API Documentation

We know that the state of our current API documentation is a pain point for many developers, and we’re in the early stages of overhauling the docs completely.

Our goals for the overhaul include:

  • Make the documentation easier to navigate (including a dedicated search bar)
  • Improve the accuracy/clarity of the information in each section
  • Add more code examples
  • Unify our apps framework documentation with the API docs
  • Make the docs more responsive to feedback from our developer community

We don’t want to rush and create more problems than we’re solving, so the timeline for this change is more on the scale of months and not weeks.

Our team also is building more “informal documentation” (guides, workarounds, etc), which we’re putting in a special section in our community. We’re hoping that these resources bridge the gap between the official docs, feature announcements, and the common issues that developers run into while building their apps: Dev Announcements and Resources

Feature Completeness

We have a dedicated R&D team that is responsible for maintaining our dev tools and API. Like you mentioned, we can’t develop every feature – and we won’t get to a place where every feature in the GUI is also available in the API. But there are some core functionalities that we can prioritize based on our users’ needs.

The primary way we decide which features to add to our API is through user feedback. Therefore, I really encourage you to go through our API feature backlog and vote for all the features you’d like to see in our API: Developer Feature Requests

If you want to read more about how we decide what to develop and which bugs to fix, check out my explanation in this thread: monday.com development priorities

Breaking Changes

We strive to not push breaking changes to our API, since we have a whole ecosystem of apps that rely on it. That said, we are human and do make mistakes. If you see any changes to our API that break the functionality of your app, please let our team know by posting in the community or reaching out to appsupport@monday.com.

Tips for using the API more effectively

Here are some tips and solutions to the topics you brought up as well.

Searching the API docs – we built the current docs as a single page so that devs can search with CMD-F/their browser’s “Find in page” functionality. However, there’s still room for improvement as this doesn’t provide results from our apps framework docs.

  • API Playground – I rely on the API playground as the main way to test the API as well.

  • 200 status code – This is actually a recommendation of the GraphQL spec. The status code reflects whether the HTTP transport was successful, and the 200 status code means “We received your query”. Any errors that arise from the GraphQL layer are surfaced in the response body (as you described).

  • Status labels – Did you manage to figure out how to retrieve the existing status labels from a board? You need to use the settings_str field on the Column object.

  • Change status color on existing column – I’m afraid this isn’t possible at the moment. Our API doesn’t allow you to manipulate labels in status or dropdown columns. I see you’ve already voted for this feature in our requests backlog! [RELEASED] Define status labels via API

I hope this gives you some additional context about our priorities. Do let me know if you have any more questions – always happy to share our efforts with users who take a genuine interest.

7 Likes